Setup Minimal GitHub Action for API Documentation (#2)

* add styles for uni bremen
* use mkdocstrings for API generation
  - see project page for details: https://mkdocstrings.github.io
  - add script to generate API pages
  - remove doxygen
  - configure reasonable API styles
  - change function docstring to correct generation

.github/workflows/deploy-mkdocs.yml

@@ -0,0 +1,23 @@
+name: Publish docs with MkDocs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[docs]"
+      - name: Deploy MkDocs
+        run: mkdocs gh-deploy --force

README.md

@@ -31,7 +31,7 @@ Common installation patterns:
 - Install with optional dependencies (as specified in [`pyproject.toml`](./pyproject.toml),
   here `test`): `pip install ".[test]"`
 
-Note: double quote is needed in `zsh` to avoid "no matches" error.
+> **_NOTE:_** double quote is needed in `zsh` to avoid "no matches" error.
 
 ## Linting
 

docs/styles/extra.css

@@ -0,0 +1,6 @@
+:root {
+  --md-primary-fg-color:        #9d2246;
+  --md-primary-fg-color--light: #d50c2f;
+  --md-primary-fg-color--dark:  #9d2246;
+  --md-accent-fg-color:         #f39ca9;
+}

mkdocs.yml

@@ -0,0 +1,77 @@
+site_name: Template Python Package
+site_description: 'A template Python Package for SECORO AG at Bremen University'
+site_author: 'SECORO AG'
+repo_url: https://github.com/secorolab/python-pkg-template
+
+nav:
+  - Home: index.md
+  # defer to gen-files + literate-nav
+  - API reference: reference/
+theme:
+  name: 'material'
+  #  logo: assets/logo.png
+  icon:
+    repo: fontawesome/brands/github
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+
+plugins:
+  - search
+  - awesome-pages
+  - gen-files:
+      scripts:
+      - scripts/gen_api_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - section-index
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          # cross-ref to other projects
+          import:
+          - https://docs.python.org/3/objects.inv
+          paths: [src]
+          options:
+            # see full list of options at https://mkdocstrings.github.io/python/usage/
+            docstring_options:
+              ignore_init_summary: true
+            docstring_section_style: list
+            merge_init_into_class: true
+            separate_signature: true
+            heading_level: 1
+            summary: true
+
+extra_css:
+  - styles/extra.css
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/secorolab
+    - icon: material/web
+      link: https://www.uni-bremen.de/secoro
+
+copyright: Copyright © 2024 SECORO Group

pyproject.toml

@@ -25,6 +25,15 @@ dependencies = [
 test = [
   "pytest",
 ]
+docs = [
+  "pathlib",                      # API generation script
+  "mkdocs-material",              # material theme
+  "mkdocs-awesome-pages-plugin",  # allow short hands for loading all markdowns
+  "mkdocstrings[python]",         # render API pages for Python
+  "mkdocs-literate-nav",          # summary API page
+  "mkdocs-gen-files",             # generate API files
+  "mkdocs-section-index",         # generate index for API
+]
 [project.urls]
 "Homepage" = "https://github.com/secorolab/python-pkg-template"
 

scripts/gen_api_pages.py

@@ -0,0 +1,38 @@
+"""Generate the API reference pages.
+
+Taken from https://mkdocstrings.github.io/recipes/
+"""
+
+from pathlib import Path
+import mkdocs_gen_files
+
+
+root = Path(__file__).parent.parent
+src = root / "src"
+
+nav = mkdocs_gen_files.Nav()
+
+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]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"---\ntitle: {ident}\n---\n\n::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

src/python_pkg_tmpl/tmpl_module.py

@@ -7,9 +7,12 @@
 
 
 def get_pkg_cache_dir(subdir: str = PKG_NAME) -> str:
-    """!Returns a subdirectory under the user's cache directory
+    """Returns a subdirectory under the user's cache directory
 
-    @param subdir subdirectory name
-    @return path to subdir in the user's cache directory
+    Parameters:
+        subdir: subdirectory name
+
+    Returns:
+        path to subdir in the user's cache directory
     """
     return join(user_cache_dir(), subdir)