From 0b7be5d08ae9cefb83300504a25d5bdb378fc51e Mon Sep 17 00:00:00 2001
From: Iziram <matthias.hartmann@iziram.fr>
Date: Wed, 24 Jul 2024 17:50:16 +0200
Subject: [PATCH] =?UTF-8?q?gen=20api=20doc=20:=20cat=C3=A9gories?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 app/api/assiduites.py   |  4 ++++
 tools/create_api_map.py | 39 +++++++++++++++++++++++++++++++++------
 2 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/app/api/assiduites.py b/app/api/assiduites.py
index 2c1c991cc..e31cb0f7b 100644
--- a/app/api/assiduites.py
+++ b/app/api/assiduites.py
@@ -341,6 +341,10 @@ def evaluation_assiduites(evaluation_id):
         ]
     }
     ```
+
+    CATEGORY
+    --------
+    evaluations
     """
     # Récupération de l'évaluation
     try:
diff --git a/tools/create_api_map.py b/tools/create_api_map.py
index 56f9dd238..963cf3946 100644
--- a/tools/create_api_map.py
+++ b/tools/create_api_map.py
@@ -4,6 +4,7 @@ Script permettant de générer une carte SVG de l'API de ScoDoc
 Écrit par Matthias HARTMANN
 """
 
+import sys
 import xml.etree.ElementTree as ET
 import re
 
@@ -508,6 +509,14 @@ def analyze_api_routes(app, endpoint_start: str) -> tuple:
                 if child.query and not href.endswith("-query"):
                     href += "-query"
 
+                # category
+
+                category: str = func.__module__.replace("app.api.", "")
+                mod_doc: str = sys.modules[func.__module__].__doc__ or ""
+                mod_doc_dict: dict = _parse_doc_string(mod_doc)
+                if mod_doc_dict.get("CATEGORY"):
+                    category = mod_doc_dict["CATEGORY"][0].strip()
+
                 permissions: str
                 try:
                     permissions: str = ", ".join(
@@ -525,6 +534,7 @@ def analyze_api_routes(app, endpoint_start: str) -> tuple:
                         "permission": permissions,
                         "description": doc_dict.get("", ""),
                         "params": doc_dict.get("PARAMS", ""),
+                        "category": doc_dict.get("CATEGORY", [False])[0] or category,
                     }
 
             # On met à jour le token courant pour le prochain segment
@@ -544,8 +554,6 @@ def gen_api_map(app, endpoint_start="api."):
     puis génère un fichier SVG à partir de cet arbre
     """
 
-    print("DEBUG", app.view_functions["apiweb.user_info"].scodoc_permission)
-
     api_map, doctable_lines = analyze_api_routes(app, endpoint_start)
 
     # On génère le SVG à partir de l'arbre de Token
@@ -903,10 +911,29 @@ def doc_route(doctable: dict) -> str:
 def gen_api_doc(app, endpoint_start="api."):
     "commande gen-api-doc"
     _, doctable_lines = analyze_api_routes(app, endpoint_start)
-    mddoc = "\n".join(
-        doc_route(doctable)
-        for doctable in sorted(doctable_lines.values(), key=lambda x: x["nom"])
-    )
+
+    mddoc: str = ""
+
+    categories: dict = {}
+    for value in doctable_lines.values():
+        category = value["category"]
+        if category not in categories:
+            categories[category] = []
+        categories[category].append(value)
+
+    # sort categories by name
+    categories: dict = dict(sorted(categories.items(), key=lambda x: x[0]))
+
+    category: str
+    routes: list[dict]
+    for category, routes in categories.items():
+        # sort routes by name
+        routes.sort(key=lambda x: x["nom"])
+
+        mddoc += f"### API {category.capitalize()}\n\n"
+        for route in routes:
+            mddoc += doc_route(route)
+            mddoc += "\n\n"
 
     fname = "/tmp/apidoc.md"
     with open(fname, "w", encoding="utf-8") as f: