Deploy docs

Bump

Fix

.github/workflows/deploy-docs.yml

@@ -1,8 +1,5 @@
-# From https://github.com/mitmproxy/pdoc/blob/main/.github/workflows/docs.yml
-# with minor adaptations
-
-name: Deploy docs
-
+# From https://github.com/mhausenblas/mkdocs-deploy-gh-pages
+name: Publish mkDocs via GitHub Pages
 # build the documentation whenever there are new commits on main
 on:
   push:
@@ -17,33 +14,17 @@ permissions:
   contents: read
 
 jobs:
-  # Build the documentation and upload the static HTML files as an artifact.
   build:
+    name: Deploy MkDocs
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: '3.10'
-
-      - run: pip install -e .[build]
-      - run: pdoc -o docs-generated/ -t docs/templates --math --docformat=numpy docs/bib/bib.py docs/dev_guide.py ./dapper
+      - name: Checkout main
+        uses: actions/checkout@v2
 
-      - uses: actions/upload-pages-artifact@v1
-        with:
-          path: docs-generated/
-
-  # Deploy the artifact to GitHub pages.
-  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - id: deployment
-        uses: actions/deploy-pages@v1
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: mkdocs.yml
+          REQUIREMENTS: requirements.txt
+          # CUSTOM_DOMAIN: optionaldomain.com

docs/gen_ref_pages.py

@@ -0,0 +1,41 @@
+"""Generate the code reference pages."""
+# Based on https://mkdocstrings.github.io/recipes/
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent
+src = root / "dapper"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1] or src.parts[-1:]
+        if not parts:
+            # we're in root pkg
+            parts = src.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
+
+    # PS: rm mkdocs_gen_files to get to inspect actual .md files
+    # NB: will (over)write in docs/ folder.
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        identifier = ".".join(parts)
+        print("::: " + identifier, file=fd)
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+# > So basically, you can use the literate-nav plugin just for its ability to
+# > infer only sub-directories, without ever writing any actual "literate navs".
+# with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+#     nav_file.writelines(nav.build_literate_nav())

mkdocs.yml

@@ -5,7 +5,7 @@ repo_url: https://github.com/nansencenter/DAPPER
 # edit_uri: edit/master/docs/
 
 docs_dir: docs
-watch: [mkdocs.yml, README.md, dapper, scripts/gen_ref_pages.py]
+watch: [mkdocs.yml, README.md, dapper]
 nav:
   - Home: index.md
   - Reference: reference/
@@ -66,7 +66,7 @@ plugins:
   # Autodoc from docstrings:
   - gen-files: # Genrate .md reflecting .py hierarchy:
       scripts:
-        - scripts/gen_ref_pages.py
+        - docs/gen_ref_pages.py
   - literate-nav: # Auto-generate nav
       nav_file: SUMMARY.md
   - section-index