Merge pull request #48 from richardkoehler/docs/update-docs

Docs/update docs

Author: richardkoehler

.github/workflows/ci.yml

@@ -128,6 +128,26 @@ jobs:
         run: |
           uv run pytest --cov-fail-under=48
 
+  prose-lint:
+    name: Prose lint (codespell + doc8 + interrogate)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Run pre-commit (prose hooks)
+        run: |
+          uv run pre-commit run --all-files codespell
+          uv run pre-commit run --all-files doc8
+          uv run pre-commit run --all-files interrogate
+
   docs:
     name: Docs (build + linkcheck)
     runs-on: ubuntu-latest
@@ -142,16 +162,34 @@ jobs:
           python-version: "3.12"
           enable-cache: true
 
+      # autosummary imports dbs_annotator modules that transitively touch
+      # PySide6; ubuntu-latest images omit the EGL/XCB libs that PySide6 needs
+      # even under QT_QPA_PLATFORM=offscreen.
+      - name: Install Qt EGL/XCB dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libegl1 \
+            libgl1 \
+            libxkbcommon0 \
+            libdbus-1-3
+
       - name: Sync docs dependency group
         run: |
           uv sync --locked --group docs --no-dev
 
       - name: Build HTML docs (warnings are errors)
+        env:
+          QT_QPA_PLATFORM: offscreen
+          MPLBACKEND: Agg
         run: |
           uv run sphinx-build -b html -W --keep-going docs docs/_build/html
 
       - name: Link check (non-blocking)
         continue-on-error: true
+        env:
+          QT_QPA_PLATFORM: offscreen
+          MPLBACKEND: Agg
         run: |
           uv run sphinx-build -b linkcheck docs docs/_build/linkcheck
 

.github/workflows/release.yml

@@ -21,9 +21,84 @@ permissions:
   contents: write
 
 jobs:
+  # ---------------------------------------------------------------------------
+  # Pre-flight gates. These run on every invocation and block all build jobs
+  # from starting if the release artifact would be inconsistent with the
+  # sources. Both gates are skipped for `workflow_dispatch` runs where
+  # `publish_release=false`, so maintainers can still dry-run the build matrix
+  # without a tag.
+  # ---------------------------------------------------------------------------
+  changelog-gate:
+    name: CHANGELOG.md has section for tag
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.publish_release) }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Verify CHANGELOG.md contains the tagged version
+        shell: bash
+        run: |
+          set -euo pipefail
+          ref="${GITHUB_REF_NAME}"
+          # Strip leading `v` (tags are `vX.Y.Z`; CHANGELOG uses `[X.Y.Z]`).
+          version="${ref#v}"
+          if ! grep -qE "^## \[${version}\]( - [0-9]{4}-[0-9]{2}-[0-9]{2})?$" CHANGELOG.md; then
+            echo "::error file=CHANGELOG.md::Missing '## [${version}]' section in CHANGELOG.md" >&2
+            echo "Expected a heading like '## [${version}] - YYYY-MM-DD' (Keep a Changelog)." >&2
+            exit 1
+          fi
+          echo "CHANGELOG.md contains a section for ${version}."
+
+  version-consistency:
+    name: Version is consistent across sources
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.publish_release) }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up uv with Python
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Verify __version__, [tool.briefcase].version, and git tag agree
+        shell: bash
+        run: |
+          set -euo pipefail
+          ref="${GITHUB_REF_NAME}"
+          tag_version="${ref#v}"
+          pkg_version=$(uv run --no-sync --no-project python -c "import re, pathlib; \
+            src = pathlib.Path('src/dbs_annotator/__init__.py').read_text(); \
+            m = re.search(r'^__version__\\s*=\\s*[\"\\'](?P<v>[^\"\\']+)[\"\\']', src, re.MULTILINE); \
+            print(m.group('v') if m else '')")
+          briefcase_version=$(uv run --no-sync --no-project python -c "import tomllib, pathlib; \
+            data = tomllib.loads(pathlib.Path('pyproject.toml').read_text()); \
+            print(data['tool']['briefcase'].get('version', ''))")
+          echo "git tag              : ${tag_version}"
+          echo "__version__          : ${pkg_version}"
+          echo "[tool.briefcase].ver : ${briefcase_version}"
+          fail=0
+          if [ "${pkg_version}" != "${tag_version}" ]; then
+            echo "::error file=src/dbs_annotator/__init__.py::__version__ (${pkg_version}) != tag (${tag_version})" >&2
+            fail=1
+          fi
+          if [ "${briefcase_version}" != "${tag_version}" ]; then
+            echo "::error file=pyproject.toml::[tool.briefcase].version (${briefcase_version}) != tag (${tag_version})" >&2
+            fail=1
+          fi
+          exit "${fail}"
+
   build-python-dist:
     name: Build Python distribution
     runs-on: ubuntu-latest
+    needs:
+      - changelog-gate
+      - version-consistency
 
     steps:
       - name: Checkout repository
@@ -49,6 +124,9 @@ jobs:
   build-briefcase-msi:
     name: Build Briefcase MSI (Windows)
     runs-on: windows-latest
+    needs:
+      - changelog-gate
+      - version-consistency
 
     steps:
       - name: Checkout repository
@@ -139,6 +217,9 @@ jobs:
   build-briefcase-macos-arm:
     name: Build Briefcase macOS DMG (arm64)
     runs-on: macos-14
+    needs:
+      - changelog-gate
+      - version-consistency
 
     steps:
       - name: Checkout repository
@@ -227,6 +308,9 @@ jobs:
   build-briefcase-linux-x86:
     name: Build Briefcase Linux package (x86_64)
     runs-on: ubuntu-latest
+    needs:
+      - changelog-gate
+      - version-consistency
 
     steps:
       - name: Checkout repository

.gitignore

@@ -68,6 +68,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/_autosummary/
 
 # PyBuilder
 .pybuilder/

.pre-commit-config.yaml

@@ -16,6 +16,25 @@ repos:
       - id: ruff-check
         args: ["--fix"]
 
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+      - id: codespell
+        additional_dependencies: ["tomli"]
+
+  - repo: https://github.com/PyCQA/doc8
+    rev: v1.1.2
+    hooks:
+      - id: doc8
+        files: ^docs/.*\.rst$
+
+  - repo: https://github.com/econchick/interrogate
+    rev: 1.7.0
+    hooks:
+      - id: interrogate
+        pass_filenames: false
+        args: ["src/dbs_annotator"]
+
   - repo: local
     hooks:
       - id: ty-check

.readthedocs.yaml

@@ -4,6 +4,15 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.12"
+  # autosummary imports PySide6 transitively when documenting modules that
+  # depend on the Qt stack (e.g. utils.theme_manager). PySide6 wheels link
+  # libEGL / libGL / libxkbcommon / libdbus even under the offscreen platform
+  # plugin, and the RTD build image does not ship these by default.
+  apt_packages:
+    - libegl1
+    - libgl1
+    - libxkbcommon0
+    - libdbus-1-3
   jobs:
     pre_install:
       - python -m pip install --upgrade pip

README.md

@@ -74,9 +74,9 @@ pip install -e .
 ### Running from Source
 
 ```bash
-python run.py
-# or
 python -m dbs_annotator
+# or, once the project is installed, the console script
+dbs-annotator
 ```
 
 ### Project Structure
@@ -94,7 +94,6 @@ App_ClinicalDBSAnnot/
 ├── styles/                       # QSS theme files (Briefcase + dev; see resource_path)
 ├── icons/                        # Application icons
 ├── scripts/                      # Utility scripts
-├── run.py                        # Development entry point
 └── pyproject.toml                # Project configuration and dependencies
 ```
 

docs/_templates/autosummary/class.rst

@@ -0,0 +1,31 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      {%- if item not in ['__init__'] %}
+      ~{{ name }}.{{ item }}
+      {%- endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/autosummary/module.rst

@@ -0,0 +1,65 @@
+{{ fullname | escape | underline }}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: autosummary/class.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: {{ _('Modules') }}
+
+.. autosummary::
+   :toctree:
+   :template: autosummary/module.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/api.rst

@@ -0,0 +1,26 @@
+API Reference
+=============
+
+This page is generated automatically from the docstrings of the
+``dbs_annotator`` package.  It is aimed at developers extending or embedding
+the application; clinicians and researchers should prefer the
+:doc:`quickstart` and :doc:`workflow_session` guides.
+
+The reference deliberately covers the **data, configuration, and control
+layers** of the application.  The Qt UI layers (``dbs_annotator.ui`` and
+``dbs_annotator.views``) are `PySide6 <https://doc.qt.io/qtforpython-6/>`_
+subclasses whose public surface is Qt signals and slots; refer to the PySide6
+documentation and the source itself for those.
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: autosummary/module.rst
+   :recursive:
+
+   dbs_annotator.config
+   dbs_annotator.config_electrode_models
+   dbs_annotator.controllers
+   dbs_annotator.logging_config
+   dbs_annotator.models
+   dbs_annotator.utils
+   dbs_annotator.version

docs/changelog.md

@@ -0,0 +1,5 @@
+# Changelog
+
+```{include} ../CHANGELOG.md
+:start-after: "# Changelog"
+```