Merge pull request #12 from febus982/autogenerate_docstrings

Autogenerate docstrings

Author: febus982

.github/workflows/release.yml

@@ -41,10 +41,10 @@ jobs:
       - name: Export version for site docs
         id: docs-version-step
         run: |
-          ./ci-scripts/docs-version.sh
-          echo "Identified version: $(./ci-scripts/docs-version.sh)"
-          echo "version=$(./ci-scripts/docs-version.sh)"
-          echo "version=$(./ci-scripts/docs-version.sh)" >> $GITHUB_OUTPUT
+          ./scripts/docs-version.sh
+          echo "Identified version: $(./scripts/docs-version.sh)"
+          echo "version=$(./scripts/docs-version.sh)"
+          echo "version=$(./scripts/docs-version.sh)" >> $GITHUB_OUTPUT
 
   publish:
     runs-on: ubuntu-latest

bootstrap_python_package/__init__.py

@@ -1,4 +1,10 @@
 def some_function() -> str:
+    """
+    Some function docstring
+
+    :return: Some string
+    :rtype: str
+    """
     return "some_variable_to_test"
 
 

mkdocs.yml

@@ -10,6 +10,15 @@ repo_url: 'https://github.com/febus982/bootstrap-python-package'
 plugins:
   - search
   - mike
+  - gen-files:
+      scripts:
+        - scripts/gen_pages.py  # or any other name or path
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: sphinx
+            docstring_section_style: spacy
 
 theme:
   name: material
@@ -44,9 +53,6 @@ extra:
     provider: mike
     default: stable
 
-nav:
-  - Home: index.md
-
 markdown_extensions:
   - pymdownx.details
   - pymdownx.blocks.admonition

pyproject.toml

@@ -45,6 +45,7 @@ coverage = ">=6.5.0"
 bandit = ">=1.7.6"
 black = ">=22.10.0"
 mkdocs = ">=1.4.3"
+mkdocstrings = { version = ">=0.24.0", extras = ["python"] }
 mkdocs-material = ">=9.1.16"
 mike = ">=2.0.0"
 mypy = ">=0.990"
@@ -55,6 +56,7 @@ pytest-cov = ">=4.0.0"
 pytest-factoryboy = ">=2.5.0"
 pytest-xdist = ">=3.0.2"
 ruff = ">=0.0.263"
+mkdocs-gen-files = "^0.5.0"
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

ci-scripts/docs-version.sh renamed to scripts/docs-version.sh

@@ -0,0 +1,51 @@
+# -----------------------------------------------------#
+#                   Library imports                    #
+# -----------------------------------------------------#
+from pathlib import Path
+
+import mkdocs_gen_files
+
+# -----------------------------------------------------#
+#                    Configuration                     #
+# -----------------------------------------------------#
+# Package source code relative path
+src_dir = "bootstrap_python_package"
+# Generated pages will be grouped in this nav folder
+nav_pages_path = "API-Reference"
+
+
+# -----------------------------------------------------#
+#                       Runner                         #
+# -----------------------------------------------------#
+""" Generate code reference pages and navigation
+
+    Based on the recipe of mkdocstrings:
+    https://github.com/mkdocstrings/mkdocstrings
+    https://github.com/mkdocstrings/mkdocstrings/issues/389#issuecomment-1100735216
+
+    Credits:
+    Timothée Mazzucotelli
+    https://github.com/pawamoy
+"""
+# Iterate over each Python file
+for path in sorted(Path(src_dir).rglob("*.py")):
+    # Get path in module, documentation and absolute
+    module_path = path.relative_to(src_dir).with_suffix("")
+    doc_path = path.relative_to(src_dir).with_suffix(".md")
+    full_doc_path = Path(nav_pages_path, doc_path)
+
+    # Handle edge cases
+    parts = (src_dir,) + tuple(module_path.parts)
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    # Write docstring documentation to disk via parser
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+    # Update parser
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)