Configuring the documentation for Sphinx and ReadTheDocs

.github/workflows/nextflow-ci.yml

@@ -5,19 +5,21 @@ on:
     branches: ["main", "dev"]
     paths:
       - "workflows/**"
+      - ".github/workflows/nextflow-ci.yml"
   pull_request:
     branches: ["main"]
     paths:
       - "workflows/**"
+      - ".github/workflows/nextflow-ci.yml"
 
 jobs:
   lint-and-test:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-java@v4
+      - uses: actions/setup-java@v5.2.0
         with:
           distribution: temurin
           java-version: 17
@@ -30,7 +32,7 @@ jobs:
 
       - name: Install nf-test
         run: |
-          NF_TEST_VERSION=$(curl -s https://api.github.com/repos/askimed/nf-test/releases/latest | jq -r .tag_name | sed 's/^v//')
+          NF_TEST_VERSION=0.9.5
           wget -qO nf-test.tar.gz "https://github.com/askimed/nf-test/releases/download/v${NF_TEST_VERSION}/nf-test-${NF_TEST_VERSION}.tar.gz"
           tar -xzf nf-test.tar.gz
           mkdir -p "$HOME/.nf-test"
@@ -39,11 +41,26 @@ jobs:
           sudo chmod +x /usr/local/bin/nf-test
 
       - name: Lint Nextflow files
+        # `nextflow lint` does not load Groovy classes from `lib/`, so it
+        # falsely reports `Helpers` as undefined wherever the workflow calls
+        # `Helpers.X(...)`. We strip ANSI colour codes from the output, drop
+        # those known false-positives, and re-derive the exit status.
         run: |
+          tmp=$(mktemp)
           nextflow lint \
             workflows/preproc/preproc_rawtiles.nf \
             workflows/reconst_3d/soct_3d_reconst.nf \
-            workflows/reconst_2.5d/soct_2.5d_reconst.nf
+            workflows/reconst_2.5d/soct_2.5d_reconst.nf \
+            > "$tmp" 2>&1 || true
+          sed 's/\x1b\[[0-9;]*[a-zA-Z]//g' "$tmp" \
+            | awk '/`Helpers` is not defined/ { skip = 3; next } skip > 0 { skip--; next } { print }' \
+            > "$tmp.filt"
+          cat "$tmp.filt"
+          if grep -qE '^Error ' "$tmp.filt"; then
+            echo "::error::nextflow lint reported errors (excluding Helpers false-positives)"
+            exit 1
+          fi
+          echo "Lint passed (Helpers false-positives ignored: lib/ classes are loaded at runtime but not by 'nextflow lint')."
 
       - name: Validate Nextflow configs
         run: |

.gitignore

@@ -18,6 +18,8 @@ eggs/
 .eggs/
 lib/
 lib64/
+!workflows/**/lib/
+!workflows/**/lib/**
 parts/
 sdist/
 var/
@@ -184,6 +186,13 @@ workflows/work/
 *.nii.gz
 *.sif
 
+# Test stub-data placeholders. The `*.zarr` rule above ignores zarr directories
+# wholesale; for nf-test stub runs we still need the empty directory markers
+# (`.gitkeep`) tracked so the workflow's input glob finds at least one
+# `mosaic_grid*.ome.zarr` directory. Re-include the directory and its keepers.
+!workflows/**/tests/data/*.ome.zarr
+!workflows/**/tests/data/*.ome.zarr/.gitkeep
+
 # Config files
 *.ini
 
@@ -196,4 +205,6 @@ draft.py
 # Exculde subject data folders (symlinks)
 sub-*
 
-.python-version
+.python-version
+# Sphinx auto-generated API docs (autoapi)
+docs/api/

.readthedocs.yaml

@@ -1,23 +1,23 @@
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# Required
 version: 2
 
-# Set the OS, Python version, and other tools you might need
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.13"
+    python: "3.12"
+  jobs:
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+      - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --extra docs --frozen
+    build:
+      html:
+        - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv run sphinx-build -T --keep-going -b html docs $READTHEDOCS_OUTPUT/html
 
-# Build documentation in the "docs/" directory with Sphinx
 sphinx:
-   configuration: docs/conf.py
-
-# Optionally, but recommended,
-# declare the Python requirements required to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#    install:
-#    - requirements: docs/requirements.txt
-
+  configuration: docs/conf.py