From 17233fb8c11850bc5762524bdb008fe687d0e68f Mon Sep 17 00:00:00 2001
From: Iziram <matthias.hartmann@iziram.fr>
Date: Wed, 24 Jul 2024 10:38:56 +0200
Subject: [PATCH] APIDoc utilisation template jinja + lien samples

---
 app/templates/apidoc.j2 | 31 +++++++++++++++++
 tools/create_api_map.py | 77 +++++++++--------------------------------
 2 files changed, 47 insertions(+), 61 deletions(-)
 create mode 100644 app/templates/apidoc.j2

diff --git a/app/templates/apidoc.j2 b/app/templates/apidoc.j2
new file mode 100644
index 000000000..36d923c94
--- /dev/null
+++ b/app/templates/apidoc.j2
@@ -0,0 +1,31 @@
+#### **`{{doc.nom}}`**
+
+{% if doc.routes %}
+{% if doc.routes|length == 1 %}
+* **Route:** `{{doc.routes[0]|safe}}`
+{% else %}
+* **Routes:**
+  {% for route in doc.routes %}
+  * `{{route|safe}}`
+  {% endfor %}
+{% endif %}
+{% endif %}
+* **Méthode:** `{{doc.method}}`
+* **Permission:** `{{doc.permission}}`
+{% if doc.params %}
+* **Paramètres:**
+  {% for param in doc.params %}
+  * `{{param.nom|safe}}` : {{param.description|safe}}
+  {% endfor %}
+{% endif %}
+{% if doc.description %}
+* **Description:** {{doc.description|safe}}
+{% endif %}
+{% if doc.data %}
+* **Data:** {{doc.data|safe}}
+{% endif %}
+
+{% if doc.sample %}
+* **Exemple de résultat:** [{{doc.sample.nom}}](./samples/sample_{{doc.sample.href}})
+{% else %}
+{% endif %}
\ No newline at end of file
diff --git a/tools/create_api_map.py b/tools/create_api_map.py
index 771f34f19..56f9dd238 100644
--- a/tools/create_api_map.py
+++ b/tools/create_api_map.py
@@ -8,6 +8,7 @@ import xml.etree.ElementTree as ET
 import re
 
 from app.auth.models import Permission
+from flask import render_template
 
 
 class COLORS:
@@ -870,79 +871,33 @@ def _write_gen_table(table: str, filename: str = "/tmp/api_table.md"):
     )
 
 
-if __name__ == "__main__":
-    # Exemple d'utilisation de la classe Token
-    # Exemple simple de création d'un arbre de Token
-
-    # root = Token("api")
-    # child1 = Token("assiduites", leaf=True)
-    # child1.func_name = "assiduites_get"
-    # child2 = Token("count")
-    # child22 = Token("all")
-    # child23 = Token(
-    #     "query",
-    #     query={
-    #         "etat": "<string:etat>",
-    #         "moduleimpl_id": "<int:moduleimpl_id>",
-    #         "count": "<int:count>",
-    #         "formsemestre_id": "<int:formsemestre_id>",
-    #     },
-    # )
-    # child3 = Token("justificatifs", "POST")
-    # child3.func_name = "justificatifs_post"
-
-    # root.add_child(child1)
-    # child1.add_child(child2)
-    # child2.add_child(child22)
-    # child2.add_child(child23)
-    # root.add_child(child3)
-
-    # group_element = root.to_svg_group()
-
-    # generate_svg(group_element, "/tmp/api_map.svg")
-    dt: dict = parse_doctable_doc(parse_doctable_doc.__doc__)
-    md: str = "POST"
-    hf: str = "assiduites-query"
-
-    doc: dict = {
-        "doctable": dt,
-        "method": md,
-        "href": hf,
-    }
-    print(_gen_table([doc]))
-
-
 def doc_route(doctable: dict) -> str:
     """Generate markdown doc for a route"""
-    doc = f"""
-#### **`{doctable['nom']}`**
+    jinja_obj: dict = {}
+    jinja_obj.update(doctable)
+    jinja_obj["nom"] = doctable["nom"].strip()  # on retire les caractères blancs
 
-"""
-    if doctable.get("routes"):
-        if len(doctable["routes"]) == 1:
-            doc += f"""* ** Route :** `{doctable["routes"][0]}`\n"""
-        else:
-            doc += "* ** Routes :**\n"
-            for route in doctable["routes"]:
-                doc += f"""    * `{route}`\n"""
-    doc += f"""* **Méthode: {doctable['method']}**
-* **Permission: `{doctable.get('permission', '')}`**
-"""
     if doctable.get("params"):
+        jinja_obj["params"] = []
         for param in doctable["params"]:
             frags = param.split(":", maxsplit=1)
             if len(frags) == 2:
                 name, descr = frags
+                jinja_obj["params"].append(
+                    {"nom": name.strip(), "description": descr.strip()}
+                )
             else:
                 print(f"Warning: {doctable['nom']} : invalid PARAMS {param}")
-                name, descr = param, ""
-            doc += f"""  * `{name}`: {descr}\n"""
-    if doctable.get("data"):
-        doc += f"""* **Data:** {doctable['data']}\n"""
     if doctable.get("description"):
         descr = "\n".join(s for s in doctable["description"])
-        doc += f"""* **Description:** {descr}\n"""
-    return doc
+        jinja_obj["description"] = descr.strip()
+
+    jinja_obj["sample"] = {
+        "nom": f"{jinja_obj['nom']}.json",
+        "href": f"{jinja_obj['nom'].replace('_', '-')}.json.md",
+    }
+
+    return render_template("apidoc.j2", doc=jinja_obj)
 
 
 def gen_api_doc(app, endpoint_start="api."):