From aac41628d13dda9bfd2a858b1f63b1a0d870382c Mon Sep 17 00:00:00 2001
From: Nicholas Junge <n.junge@appliedai.de>
Date: Thu, 21 Mar 2024 09:39:56 +0100
Subject: [PATCH] Rollforward of lakefs-spec doc changes (#123)

This is the same change set for the docpage generation script, see
https://github.com/aai-institute/lakefs-spec/pull/273.

Co-authored-by: Adrian Rumpold <a.rumpold@gmail.com>
---
 docs/_scripts/gen_api_ref_pages.py | 30 ++++++++++++++++++++++++++++++
 pyproject.toml                     |  1 +
 requirements-docs.txt              |  1 +
 3 files changed, 32 insertions(+)

diff --git a/docs/_scripts/gen_api_ref_pages.py b/docs/_scripts/gen_api_ref_pages.py
index 1f94aa9..b51e15b 100644
--- a/docs/_scripts/gen_api_ref_pages.py
+++ b/docs/_scripts/gen_api_ref_pages.py
@@ -1,10 +1,15 @@
 """Automatically generate API reference pages from source files.
 
 Source: https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages
+
+Note: this script assumes a source layout with a `src/` folder.
 """
 
+import ast
+import logging
 from pathlib import Path
 
+import docstring_parser
 import mkdocs_gen_files
 
 nav = mkdocs_gen_files.Nav()
@@ -31,5 +36,30 @@
 
     mkdocs_gen_files.set_edit_path(full_doc_path, path)
 
+# Add links for top-level modules to root page
+root_page = next(it for it in nav.items() if it.level == 0)
+children = [it for it in nav.items() if it.level == 1]
+
+with mkdocs_gen_files.open(f"reference/{root_page.filename}", "a") as f:
+    f.write("## Modules\n")
+    for ch in children:
+        f.write(f"### [{ch.title}](../{ch.filename})\n")
+
+        try:
+            source_file = Path("src", ch.filename).with_suffix(".py")
+
+            # Index page for submodules maps to __init__.py of the module
+            if source_file.stem == "index":
+                source_file = source_file.with_stem("__init__")
+
+            tree = ast.parse(source_file.read_text())
+            docstring = ast.get_docstring(tree, clean=False)
+            doc = docstring_parser.parse(docstring)
+
+            if doc.short_description:
+                f.write(f"{doc.short_description}\n\n")
+        except Exception as e:
+            logging.warning(f"Could not parse module docstring: {ch.filename}", exc_info=True)
+
 with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
     nav_file.writelines(nav.build_literate_nav())
diff --git a/pyproject.toml b/pyproject.toml
index f20b3aa..78f0810 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -52,6 +52,7 @@ dev = [
 ]
 docs = [
     "black",
+    "docstring-parser",
     "mike",
     "mkdocs",
     "mkdocs-callouts",
diff --git a/requirements-docs.txt b/requirements-docs.txt
index 06d2b48..1d2177b 100644
--- a/requirements-docs.txt
+++ b/requirements-docs.txt
@@ -11,6 +11,7 @@ certifi==2024.2.2
 charset-normalizer==3.3.2
 click==8.1.7
 colorama==0.4.6
+docstring-parser==0.16
 essentials==1.1.5
 essentials-openapi==1.0.9
 ghp-import==2.1.0