From 188534819be120770670550f06e8a281240b3e5f Mon Sep 17 00:00:00 2001 From: Emmanuel Viennet Date: Thu, 25 Jul 2024 10:42:49 +0200 Subject: [PATCH] =?UTF-8?q?Documentation=20API:=20correctifs=20+=20g=C3=A9?= =?UTF-8?q?n=C3=A9ration=20page=20compl=C3=A8te?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- app/api/evaluations.py | 24 +++++++++++++--------- app/api/formations.py | 16 +++++++-------- app/api/jury.py | 1 - app/api/moduleimpl.py | 34 +++++++++++++++++-------------- app/api/semset.py | 1 - app/templates/{ => doc}/apidoc.j2 | 5 +++-- tools/create_api_map.py | 14 ++++++++----- 7 files changed, 53 insertions(+), 42 deletions(-) rename app/templates/{ => doc}/apidoc.j2 (81%) diff --git a/app/api/evaluations.py b/app/api/evaluations.py index 6e936b9b..86509059 100644 --- a/app/api/evaluations.py +++ b/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: diff --git a/app/api/formations.py b/app/api/formations.py index 94b984a4..7f8146cc 100644 --- a/app/api/formations.py +++ b/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") diff --git a/app/api/jury.py b/app/api/jury.py index aeec7982..29ed2dc7 100644 --- a/app/api/jury.py +++ b/app/api/jury.py @@ -199,7 +199,6 @@ def validation_rcue_record(etudid: int): DATA ---- - ```json { "code" : str, diff --git a/app/api/moduleimpl.py b/app/api/moduleimpl.py index 1771927a..26cafa03 100644 --- a/app/api/moduleimpl.py +++ b/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) diff --git a/app/api/semset.py b/app/api/semset.py index 7822cc58..981c5a09 100644 --- a/app/api/semset.py +++ b/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 diff --git a/app/templates/apidoc.j2 b/app/templates/doc/apidoc.j2 similarity index 81% rename from app/templates/apidoc.j2 rename to app/templates/doc/apidoc.j2 index 36d923c9..d5825f83 100644 --- a/app/templates/apidoc.j2 +++ b/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 %} diff --git a/tools/create_api_map.py b/tools/create_api_map.py index 963cf394..fdc798d8 100644 --- a/tools/create_api_map.py +++ b/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}"