Documentation API: correctifs + génération page complète

app/api/evaluations.py

@@ -105,25 +105,29 @@ def evaluation_notes(evaluation_id: int):
     evaluation_id : l'id de l'évaluation
 
     Exemple de résultat :
-        {
-          "11": {
+    ```json
+    {
+        "11": {
             "etudid": 11,
             "evaluation_id": 1,
             "value": 15.0,
+            "note_max" : 20.0,
             "comment": "",
-            "date": "Wed, 20 Apr 2022 06:49:05 GMT",
+            "date": "2024-07-19T19:08:44+02:00",
             "uid": 2
-          },
-          "12": {
+        },
+        "12": {
             "etudid": 12,
             "evaluation_id": 1,
-            "value": 12.0,
+            "value": "ABS",
+            "note_max" : 20.0,
             "comment": "",
-            "date": "Wed, 20 Apr 2022 06:49:06 GMT",
+            "date": "2024-07-19T19:08:44+02:00",
             "uid": 2
-          },
-          ...
-        }
+        },
+        ...
+    }
+    ```
     """
     query = Evaluation.query.filter_by(id=evaluation_id)
     if g.scodoc_dept:

app/api/formations.py

@@ -411,11 +411,11 @@ def ue_set_code_apogee(ue_id: int | None = None, code_apogee: str = ""):
 
     Ce changement peut être fait sur formation verrouillée.
 
-    Si ue_id n'est pas spécifié, utilise l'argument oid du POST.
-    Si code_apogee n'est pas spécifié ou vide,
+    Si `ue_id` n'est pas spécifié, utilise l'argument oid du POST.
+    Si `code_apogee` n'est pas spécifié ou vide,
     utilise l'argument value du POST.
 
-    Le retour est une chaîne (le code enregistré), pas json.
+    Le retour est une chaîne (le code enregistré), pas du json.
     """
     if ue_id is None:
         ue_id = request.form.get("oid")
@@ -468,9 +468,9 @@ def ue_set_code_apogee_rcue(ue_id: int, code_apogee: str = ""):
     Ce changement peut être fait sur formation verrouillée.
 
     Si code_apogee n'est pas spécifié ou vide,
-    utilise l'argument value du POST (utilisé par jinplace.js)
+    utilise l'argument value du POST (utilisé par `jinplace.js`)
 
-    Le retour est une chaîne (le code enregistré), pas json.
+    Le retour est une chaîne (le code enregistré), pas du json.
     """
     if not code_apogee:
         code_apogee = request.form.get("value", "")
@@ -522,11 +522,11 @@ def formation_module_set_code_apogee(
 
     Ce changement peut être fait sur formation verrouillée.
 
-    Si module_id n'est pas spécifié, utilise l'argument oid du POST.
-    Si code_apogee n'est pas spécifié ou vide,
+    Si `module_id` n'est pas spécifié, utilise l'argument `oid` du POST.
+    Si `code_apogee` n'est pas spécifié ou vide,
     utilise l'argument value du POST (utilisé par jinplace.js)
 
-    Le retour est une chaîne (le code enregistré), pas json.
+    Le retour est une chaîne (le code enregistré), pas du json.
     """
     if module_id is None:
         module_id = request.form.get("oid")

app/api/jury.py

@@ -199,7 +199,6 @@ def validation_rcue_record(etudid: int):
 
     DATA
     ----
-
     ```json
     {
         "code" : str,

app/api/moduleimpl.py

@@ -106,22 +106,26 @@ def moduleimpl_inscriptions(moduleimpl_id: int):
 @scodoc
 @permission_required(Permission.ScoView)
 def moduleimpl_notes(moduleimpl_id: int):
-    """Liste des notes dans ce moduleimpl
+    """Liste des notes dans ce moduleimpl.
+
     Exemple de résultat :
-        [
-          {
-            "etudid": 17776, // code de l'étudiant
-            "nom": "DUPONT",
-            "prenom": "Luz",
-            "38411": 16.0, // Note dans l'évaluation d'id 38411
-            "38410": 15.0,
-            "moymod": 15.5, // Moyenne INDICATIVE module
-            "moy_ue_2875": 15.5, // Moyenne vers l'UE 2875
-            "moy_ue_2876": 15.5, // Moyenne vers l'UE 2876
-            "moy_ue_2877": 15.5  // Moyenne vers l'UE 2877
-          },
-          ...
-        ]
+
+    ```json
+    [
+      {
+        "etudid": 17776, // code de l'étudiant
+        "nom": "DUPONT",
+        "prenom": "Luz",
+        "38411": 16.0, // Note dans l'évaluation d'id 38411
+        "38410": 15.0,
+        "moymod": 15.5, // Moyenne INDICATIVE module
+        "moy_ue_2875": 15.5, // Moyenne vers l'UE 2875
+        "moy_ue_2876": 15.5, // Moyenne vers l'UE 2876
+        "moy_ue_2877": 15.5  // Moyenne vers l'UE 2877
+      },
+      ...
+    ]
+    ```
     """
     modimpl = ModuleImpl.get_modimpl(moduleimpl_id)
     app.set_sco_dept(modimpl.formsemestre.departement.acronym)

app/api/semset.py

@@ -6,7 +6,6 @@
 
 """
   ScoDoc 9 API : accès aux formsemestres
-
 """
 # from flask import g, jsonify, request
 # from flask_login import login_required

app/templates/doc/apidoc.j2

@@ -1,3 +1,4 @@
+{# Template pour la doc mardown d'un point d'entrée de l'API #}
 #### **`{{doc.nom}}`**
 
 {% if doc.routes %}
@@ -6,7 +7,7 @@
 {% else %}
 * **Routes:**
   {% for route in doc.routes %}
-  * `{{route|safe}}`
+    * `{{route|safe}}`
   {% endfor %}
 {% endif %}
 {% endif %}
@@ -15,7 +16,7 @@
 {% if doc.params %}
 * **Paramètres:**
   {% for param in doc.params %}
-  * `{{param.nom|safe}}` : {{param.description|safe}}
+    * `{{param.nom|safe}}` : {{param.description|safe}}
   {% endfor %}
 {% endif %}
 {% if doc.description %}

tools/create_api_map.py

@@ -547,7 +547,7 @@ def analyze_api_routes(app, endpoint_start: str) -> tuple:
 
 
 # point d'entrée de la commande `flask gen-api-map`
-def gen_api_map(app, endpoint_start="api."):
+def gen_api_map(app, endpoint_start="api.") -> str:
     """
     Fonction permettant de générer une carte SVG de l'API de ScoDoc
     Elle récupère les routes de l'API et les transforme en un arbre de Token
@@ -566,6 +566,7 @@ def gen_api_map(app, endpoint_start="api."):
     # On génère le tableau à partir de doctable_lines
     table = _gen_table(sorted(doctable_lines.values(), key=lambda x: x["nom"]))
     _write_gen_table(table)
+    return table
 
 
 def _get_bbox(element, x_offset=0, y_offset=0):
@@ -905,7 +906,7 @@ def doc_route(doctable: dict) -> str:
         "href": f"{jinja_obj['nom'].replace('_', '-')}.json.md",
     }
 
-    return render_template("apidoc.j2", doc=jinja_obj)
+    return render_template("doc/apidoc.j2", doc=jinja_obj)
 
 
 def gen_api_doc(app, endpoint_start="api."):
@@ -922,7 +923,7 @@ def gen_api_doc(app, endpoint_start="api."):
         categories[category].append(value)
 
     # sort categories by name
-    categories: dict = dict(sorted(categories.items(), key=lambda x: x[0]))
+    categories: dict = dict(sorted(categories.items(), key=lambda x: x[0].capitalize()))
 
     category: str
     routes: list[dict]
@@ -935,9 +936,12 @@ def gen_api_doc(app, endpoint_start="api."):
             mddoc += doc_route(route)
             mddoc += "\n\n"
 
-    fname = "/tmp/apidoc.md"
+    table_api = gen_api_map(app, endpoint_start=endpoint_start)
+    mdpage = render_template("doc/ScoDoc9API.j2", doc_api=mddoc, table_api=table_api)
+
+    fname = "/tmp/ScoDoc9API.md"
     with open(fname, "w", encoding="utf-8") as f:
-        f.write(mddoc)
+        f.write(mdpage)
     print(
         "La documentation API a été générée avec succès. "
         f"Vous pouvez la consulter à l'adresse suivante : {fname}"