From f7a8c1d2dbd9909673ea172c734e5632ad1450ea Mon Sep 17 00:00:00 2001
From: Iziram <matthias.hartmann@iziram.fr>
Date: Thu, 25 Jul 2024 11:45:26 +0200
Subject: [PATCH] API Doc : lien query OK
---
tools/create_api_map.py | 74 ++++++++++++-----------------------------
1 file changed, 21 insertions(+), 53 deletions(-)
diff --git a/tools/create_api_map.py b/tools/create_api_map.py
index 1bd65df6..a1489e69 100644
--- a/tools/create_api_map.py
+++ b/tools/create_api_map.py
@@ -503,8 +503,6 @@ def analyze_api_routes(app, endpoint_start: str) -> tuple:
child.method = method
current_token.add_child(child)
- # Gestion de doctable
- doctable = parse_doctable_doc(func.__doc__ or "")
href = func_name
if child.query and not href.endswith("-query"):
href += "-query"
@@ -527,10 +525,10 @@ def analyze_api_routes(app, endpoint_start: str) -> tuple:
if func_name not in doctable_lines:
doctable_lines[func_name] = {
- "doctable": doctable,
"method": method,
"nom": func_name,
"href": href,
+ "query": doc_dict.get("QUERY", "") != "",
"permission": permissions,
"description": doc_dict.get("", ""),
"params": doc_dict.get("PARAMS", ""),
@@ -745,23 +743,6 @@ def _get_doc_lines(keyword, doc_string: str) -> list[str]:
return kw_lines
-def parse_doc_name(doc_string: str) -> str:
- """
- renvoie le nom de la route à partir de la docstring
-
- La doc doit contenir des lignes de la forme:
-
- DOC_ANCHOR
- ----------
- nom_de_la_route
-
- Il ne peut y avoir qu'une seule ligne suivant -----
-
- """
- name_lines: list[str] = _get_doc_lines("DOC_ANCHOR", doc_string)
- return name_lines[0] if name_lines else None
-
-
def parse_query_doc(doc_string: str) -> dict[str, str]:
"""
renvoie un dictionnaire {param: <type:nom_param>} (ex: {assiduite_id : <int:assiduite_id>})
@@ -795,45 +776,28 @@ def parse_query_doc(doc_string: str) -> dict[str, str]:
return query
-def parse_doctable_doc(doc_string: str) -> dict[str, str]:
+def _gen_table_line(doctable: dict = None):
"""
- Retourne un dictionnaire représentant les informations du tableau d'api
- à partir de la doc (DOC-TABLE)
-
- éléments optionnels:
- - `permissions` permissions nécessaires pour accéder à la route (ScoView, AbsChange, ...)
- - `href` nom (sans #) de l'ancre dans la page ScoDoc9API
+ Génère une ligne de tableau markdown
- DOC-TABLE
- ---------
- permissions: ScoView
- href: une-fonction
+ | nom de la route| methode HTTP| Permission |
"""
- doc_lines: list[str] = _get_doc_lines("DOC-TABLE", doc_string)
- table = {}
-
- # on parcourt les lignes de la doc
- for line in doc_lines:
- # On sépare le paramètre et sa valeur
- param, value = line.split(":")
- # On met à jour le dictionnaire
- table[param.strip()] = value.strip()
+ nom, method, permission = (
+ doctable.get("nom", ""),
+ doctable.get("method", ""),
+ doctable.get("permission", ""),
+ )
- return table
+ if doctable is None:
+ doctable = {}
+ lien: str = doctable.get("href", nom)
-def _gen_table_line(
- nom="", href="", method="", permission="", doctable: dict = None, **kwargs
-):
- """
- Génère une ligne de tableau markdown
+ doctable["query"]: bool
+ if doctable.get("query") and not lien.endswith("-query"):
+ lien += "-query"
- | nom de la route| methode HTTP| Permission |
- """
- lien: str = href
- if "href" in doctable:
- lien: str = doctable.get("href")
nav: str = f"[{nom}]({'#'+lien})"
table: str = "|"
@@ -867,7 +831,7 @@ def _gen_table(lines: list[dict]) -> str:
"""
table = _gen_table_head()
- table += "\n".join([_gen_table_line(**line) for line in lines])
+ table += "\n".join([_gen_table_line(line) for line in lines])
return table
@@ -886,6 +850,10 @@ def doc_route(doctable: dict) -> str:
jinja_obj.update(doctable)
jinja_obj["nom"] = doctable["nom"].strip() # on retire les caractères blancs
+ jinja_obj["query"]: bool
+ if jinja_obj["query"]:
+ jinja_obj["nom"] += "(-query)"
+
if doctable.get("params"):
jinja_obj["params"] = []
for param in doctable["params"]:
@@ -903,7 +871,7 @@ def doc_route(doctable: dict) -> str:
jinja_obj["sample"] = {
"nom": f"{jinja_obj['nom']}.json",
- "href": f"{jinja_obj['nom'].replace('_', '-')}.json.md",
+ "href": f"{jinja_obj['nom']}.json.md",
}
return render_template("doc/apidoc.j2", doc=jinja_obj)
--
GitLab