Merge pull request #11 from yaptide/5-include-reference-in-docs-like-…

…in-backend-repo

Generating ref page and test coverage

.github/workflows/docs.yml

@@ -38,6 +38,10 @@ jobs:
         uses: actions/setup-python@v5
         with:
             python-version: '3.12'
+      - name: Clone backend repo
+        uses: actions/checkout@v4
+        with:
+          repository: 'yaptide/yaptide'
       - name: Update pip and install poetry
         run: |
           python3 -m pip install --upgrade pip

docs/backend/gen_ref_pages.py

@@ -0,0 +1,33 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+for path in sorted(Path("yaptide").rglob("*.py")):
+    module_path = path.relative_to("yaptide").with_suffix("")
+    doc_path = path.relative_to("yaptide").with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__" or parts[-1] == "cli":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())
+
+# copy the openapi.yaml file from the flask_static directory to the docs directory
+flask_static_openapi_path = Path('yaptide', 'static', 'openapi.yaml')
+mkdocs_openapi_path = Path('docs', 'openapi.yaml')
+mkdocs_openapi_path.write_text(flask_static_openapi_path.read_text())

mkdocs.yml

@@ -18,6 +18,8 @@ nav:
   - Jobs and tasks: backend/states.md
   - Persistent storage: backend/persistency.md
   - Docker images on GHCR: backend/ghcr_packages.md
+  - Code Reference: reference/
+  - Test coverage: coverage.md
 - Frontend:
   - Overview: frontend/index.md
   - For developers: frontend/for_developers.md
@@ -31,6 +33,9 @@ nav:
 
 plugins:
 - search
+- gen-files:
+    scripts:
+    - docs/backend/gen_ref_pages.py
 - literate-nav:
     nav_file: SUMMARY.md
 - section-index