Merge pull request #198 from alan-turing-institute/docs

Add basic `mkdocs` config

.github/workflows/ci.yaml

@@ -57,3 +57,39 @@ jobs:
       #   with:
       #     # If you use a different name, update COMMENT_ARTIFACT_NAME accordingly
       #     name: python-coverage-comment-action
+
+  docs:
+    needs: [pre-commit, pytest]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      # - name: Download coverage svg
+      #   uses: actions/download-artifact@v3
+      #   with:
+      #     name: coverage-badge
+      #     path: docs/assets/
+      #
+      # - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      #   name: Update cache_id
+      #
+      - name: Apply mkdocs cache
+        uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install doc dependencies via poetry
+        run: |
+          pip install poetry
+          poetry install --with dev
+
+      - name: Build docs with gh-deploy --force
+        run: |
+          poetry run mkdocs gh-deploy --force

docs/gen_ref_pages.py

@@ -0,0 +1,69 @@
+"""Generate documentation pages from docstrings."""
+
+from logging import getLogger
+from pathlib import Path
+from typing import Generator
+
+import mkdocs_gen_files
+
+logger = getLogger(__name__)
+
+
+CODE_PATH: Path = Path()
+CODE_DOC_REGEX: str = "*.py"
+DOC_SUFFIX: str = ".md"
+GEN_DOC_PATH: str = "reference"
+DOC_NAV_FILE_NAME: str = "DOC_STRINGS.md"
+DOC_NAV_FILE_PATH: Path = Path(str(GEN_DOC_PATH)) / str(DOC_NAV_FILE_NAME)
+
+EXCLUDE_PATHS: tuple[str, ...] = (
+    "azure",
+    "data",
+    "docker",
+    "meeting_notes",
+    "notebooks",
+    "docs",
+    "tests",
+)
+
+nav: mkdocs_gen_files.Nav = mkdocs_gen_files.Nav()
+
+
+for path in sorted(CODE_PATH.rglob(CODE_DOC_REGEX)):
+    module_path: Path = path.relative_to(str(CODE_PATH)).with_suffix("")
+    doc_path: Path = path.relative_to(str(CODE_PATH)).with_suffix(DOC_SUFFIX)
+
+    full_doc_path: Path = Path(str(GEN_DOC_PATH), doc_path)
+
+    parts: tuple[str, ...] = tuple(module_path.parts)
+    logger.debug(f"Managing module path {parts}")
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        if len(parts) == 0:
+            logger.debug(f"Skipping {parts}")
+            continue
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__" or set(EXCLUDE_PATHS) & set(parts):
+        logger.debug(f"Skipping module path {parts}")
+        continue
+
+    logger.debug(f"Will write to {full_doc_path}")
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        doc_md_path: str = ".".join(parts)
+        section_heading: str = "::: " + doc_md_path
+        logger.debug(f"Adding {section_heading}")
+        fd.write(section_heading)
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+
+with mkdocs_gen_files.open(DOC_NAV_FILE_PATH, "w") as nav_file:
+    logger.warning(f"Opening {DOC_NAV_FILE_NAME} to generate navigation file.")
+    literate_nav_str: Generator = nav.build_literate_nav()
+    logger.debug(f"Writing:\n{literate_nav_str}")
+    nav_file.writelines(literate_nav_str)

mkdocs.yml

@@ -0,0 +1,94 @@
+site_name: 'Reginald: a simple Slack bot written in Python'
+dev_addr: '127.0.0.1:9000'
+docs_dir: .
+
+nav:
+  - Home: README.md
+  - Models: MODELS.md
+  - Configuration: ENVIRONMENT_VARIABLES.md
+  - Issues: https://github.com/alan-turing-institute/reginald/issues
+  - Reference: reference/
+
+repo_url: https://github.com/alan-turing-institute/reginald/
+
+watch:
+  - docs
+
+theme:
+  name: material
+  features:
+    - content.code.copy
+    - content.tabs.link
+  palette:
+    # Palette toggle for automatic mode
+    - media: '(prefers-color-scheme)'
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: '(prefers-color-scheme: light)'
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: '(prefers-color-scheme: dark)'
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+
+plugins:
+  - search:
+      lang: en
+  - same-dir
+  # optional
+  # - include-markdown
+  # - markdown-exec
+  - gen-files:
+      scripts:
+        - docs/gen_ref_pages.py
+  - literate-nav:
+      nav_file: DOC_STRINGS.md
+  - section-index
+  - autorefs
+
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [.]
+          options:
+            docstring_style: numpy
+            separate_signature: true
+            show_signature_annotations: true
+            annotations_path: brief
+            line_length: 80
+            signature_crossrefs: true
+            merge_init_into_classes: true
+
+markdown_extensions:
+  - smarty
+  - admonition
+  - pymdownx.details
+  - abbr
+  - attr_list
+  - tables
+  - footnotes
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+      use_pygments: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.magiclink
+#
+# extra_css:
+#   - css/code_select.css