Project setup (#37)

* feat(docs): Add bare-bones mkdocs documentation; package metadata

* feat(ci): Docs workflow and reusable CI actions

* chore: Add docs output folder to dockerignore

* chore: Add fallback version for setuptools-scm

This is required for wheel builds in Docker image builds, where the .git
folder is not available and no other version information can be used.

* fix: Set restart policy for Minikube container in bootstrap script

.dockerignore

@@ -10,3 +10,4 @@
 .envrc
 data
 tests
+public

.github/actions/mike-docs/action.yaml

@@ -0,0 +1,35 @@
+name: Documentation
+description: Build and publish documentation using mike
+inputs:
+  version:
+    description: Version number
+    required: true
+  alias:
+    description: Alias name
+  push:
+    description: Whether to push the built documentation to the repository
+    required: true
+    default: "false"
+  pre_release:
+    description: Whether this version is a pre-release version (to render a notification banner)
+    default: "false"
+runs:
+  using: "composite"
+  steps:
+    - run: |
+        # https://github.com/jimporter/mike#deploying-via-ci
+        git fetch origin gh-pages --depth=1
+
+        # For proper UI integration: https://github.com/actions/checkout/pull/1184
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      shell: bash
+    - env:
+        DOCS_PRERELEASE: ${{ inputs.pre_release }}
+      run: |
+        MIKE_OPTIONS=( "--update-aliases" )
+        if [ "true" = "${{ inputs.push }}" ]; then
+          MIKE_OPTIONS+=( "--push" )
+        fi
+        mike deploy ${{ inputs.version }} ${{ inputs.alias }} "${MIKE_OPTIONS[@]}"
+      shell: bash

.github/actions/python-deps/action.yaml

@@ -0,0 +1,19 @@
+name: Install Python dependencies
+description: Install all core and optional Python dependencies
+inputs:
+  pythonVersion:
+    description: Python version to set up (see actions/setup-python@v5)
+    required: true
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.pythonVersion }}
+    - name: Install Python dependencies
+      run: |
+        pip install -U pip uv
+        uv pip install --system -r requirements-dev.txt
+        uv pip install --system --no-deps .
+      shell: bash

.github/workflows/docs.yaml

@@ -0,0 +1,47 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python and dependencies
+        uses: ./.github/actions/python-deps
+        with:
+          pythonVersion: "3.11"
+      - name: Build documentation
+        run: mkdocs build
+      - name: Archive built documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: public/docs
+  deploy-docs:
+    runs-on: ubuntu-latest
+    name: Deploy documentation to GitHub Pages
+    # publish on 'main' only to prevent version clutter
+    if: ${{ github.ref == 'refs/heads/main' }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python and dependencies
+        uses: ./.github/actions/python-deps
+        with:
+          pythonVersion: "3.11"
+      - name: Restore built docs from artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: backend_docker
+          path: public/docs
+      - name: Publish documentation
+        uses: ./.github/actions/mike-docs
+        with:
+          version: ${{ github.event.release.tag_name }}
+          alias: latest

.github/workflows/test-and-lint.yaml → .github/workflows/python.yaml

@@ -1,4 +1,4 @@
-name: Lint and test jobs poc
+name: Python library
 
 on:
   push:
@@ -20,16 +20,10 @@ jobs:
       PRE_COMMIT_HOME: "${{ github.workspace }}/.cache/pre-commit"
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
       - name: Set up Python and dependencies
-        uses: actions/setup-python@v5
+        uses: ./.github/actions/python-deps
         with:
-          python-version: 3.11
-      - name: Install dependencies
-        run: |
-          pip install -U uv
-          uv pip install --no-deps . -r requirements-dev.txt
+          pythonVersion: "3.11"
       - name: Cache pre-commit tools
         uses: actions/cache@v4
         with:
@@ -50,12 +44,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Set up oldest supported Python on ${{ matrix.os }}
-        uses: actions/setup-python@v5
+        uses: ./.github/actions/python-deps
         with:
-          python-version: "3.10"
-      - name: Run tests on oldest supported Python
+          pythonVersion: "3.10"
+      - name: Execute python tests
         run: |
-          pip install -U uv
-          uv pip install -r requirements-dev.txt
           uv pip install .  # need to install without --no-deps to work around non-portable dependency resolution in `uv pip compile`
           pytest

.pre-commit-config.yaml

@@ -9,6 +9,7 @@ repos:
       - id: check-toml
       - id: check-yaml
         args: [--allow-multiple-documents]
+        exclude: "mkdocs.yml"
       - id: end-of-file-fixer
       - id: mixed-line-ending
   - repo: https://github.com/astral-sh/ruff-pre-commit

docs/_scripts/gen_api_ref_pages.py

@@ -0,0 +1,67 @@
+"""Automatically generate API reference pages from source files.
+
+Source: https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages
+
+Note: this script assumes a source layout with a `src/` folder.
+"""
+
+import ast
+import logging
+from pathlib import Path
+
+import docstring_parser
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+for path in sorted(Path("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 = list(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:
+        identifier = ".".join(parts)
+        print("::: " + identifier, file=fd)
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+# Add links for top-level modules to root page
+root_page = next(it for it in nav.items() if it.level == 0)
+children = [it for it in nav.items() if it.level == 1]
+
+with mkdocs_gen_files.open(f"reference/{root_page.filename}", "a") as f:
+    f.write("## Modules\n")
+    for ch in children:
+        f.write(f"### [{ch.title}](../{ch.filename})\n")
+
+        try:
+            source_file = Path("src", ch.filename).with_suffix(".py")
+
+            # Index page for submodules maps to __init__.py of the module
+            if source_file.stem == "index":
+                source_file = source_file.with_stem("__init__")
+
+            tree = ast.parse(source_file.read_text())
+            docstring = ast.get_docstring(tree, clean=False)
+            doc = docstring_parser.parse(docstring)
+
+            if doc.short_description:
+                f.write(f"{doc.short_description}\n\n")
+        except Exception as e:
+            logging.warning(
+                f"Could not parse module docstring: {ch.filename}", exc_info=True
+            )
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/_styles/extra.css

@@ -0,0 +1,28 @@
+/*Remove leading `!` from code cells, which use the cell magic for shell commands*/
+code > .err:first-of-type {
+  display: none;
+}
+
+/* Hide empty root heading (-> `#`) */
+h1#_1 {
+  display: none;
+}
+
+.logo {
+  /* No wider than the screen on smaller screens */
+  max-width: min(100%, 100vw) !important;
+  max-height: 196px;
+
+  /* Horizontally centered */
+  display: block;
+  margin: 0 auto;
+}
+
+table {
+  display: block;
+  max-width: -moz-fit-content;
+  max-width: fit-content;
+  margin: 0 auto;
+  overflow-x: auto;
+  white-space: nowrap;
+}

docs/_styles/theme.css

@@ -0,0 +1,36 @@
+[data-md-color-scheme="aai-light"] {
+    /* Primary color shades */
+    --md-primary-fg-color: #084059;
+    --md-primary-fg-color--light: #46add5;
+    --md-primary-fg-color--dark: #04212f;
+
+    --md-typeset-a-color: var(--md-primary-fg-color);
+
+    /* Accent color shades */
+    --md-accent-fg-color: var(--md-primary-fg-color--light);
+
+    --md-code-font-family: "Source Code Pro", monospace
+}
+
+[data-md-color-scheme="slate"] {
+    --md-primary-fg-color: #46add5;
+    --md-primary-fg-color--dark: #04212f;
+    --md-accent-fg-color: hsl(197, 63%, 75%);
+
+    --md-typeset-a-color: var(--md-primary-fg-color) !important;
+
+    --md-accent-fg-color: var(--md-primary-fg-color);
+
+    --md-code-font-family: "Source Code Pro", monospace
+}
+
+[data-md-color-scheme="aai-light"] img[src$="#only-dark"],
+[data-md-color-scheme="aai-light"] img[src$="#gh-dark-mode-only"] {
+    display: none;
+    /* Hide dark images in light mode */
+}
+
+.md-header {
+    background: rgb(24, 165, 167);
+    background: linear-gradient(30deg, rgb(24, 165, 167), 90%, rgb(191, 255, 199));
+}

docs/_theme_overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+{% block announce %}
+{%- if config.extra.pre_release -%}
+You are currently viewing <strong>pre-release</strong> documentation. This may contain features that have not yet been
+released. For the most accurate information, please <strong><a href="{{ '../' ~ base_url }}">access the latest
+    release</a></strong>.
+{%- endif -%}
+{% endblock %}