BLD/CI: update docs build process

.github/workflows/documentation.yml

@@ -19,15 +19,15 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          ref: ${{ github.sha }}
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
           persist-credentials: false
       - uses: prefix-dev/[email protected]
         with:
           pixi-version: v0.81.0
           manifest-path: pyproject.toml
           run-install: false
           cache: false
-      - name: Resolve released dependencies once for this workflow
+      - name: Resolve example dependencies once for this workflow
         run: pixi update sequince sequince-density
       - uses: actions/upload-artifact@v4
         with:
@@ -48,7 +48,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          ref: ${{ github.sha }}
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
           persist-credentials: false
       - uses: actions/download-artifact@v4
         with:
@@ -81,7 +81,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          ref: ${{ github.sha }}
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
           persist-credentials: false
       - uses: actions/download-artifact@v4
         with:

.github/workflows/pr-documentation.yml

@@ -0,0 +1,35 @@
+name: Publish PR documentation
+on:
+  workflow_run:
+    workflows: [Example documentation]
+    types: [completed]
+
+permissions:
+  actions: read
+  contents: write
+  pull-requests: read
+
+jobs:
+  publish:
+    if: >-
+      github.repository == 'sequince-dev/sequince-examples' &&
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    timeout-minutes: 55
+    concurrency:
+      group: examples-rtd-pr-${{ github.event.workflow_run.head_repository.full_name }}-${{ github.event.workflow_run.head_branch }}
+      cancel-in-progress: false
+    steps:
+      # workflow_run uses trusted default-branch code. Never check out the PR
+      # or execute files from its artifacts in this credential-bearing job.
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+      - name: Publish bundle and rebuild PR preview
+        run: python3 scripts/publish_pr_docs.py
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RTD_TOKEN: ${{ secrets.RTD_TOKEN }}
+          RTD_PROJECT: ${{ vars.RTD_PROJECT }}

CONTRIBUTING.md

@@ -43,8 +43,9 @@ Keep local `main` for upstream changes and develop on separate branches. Install
 [Pixi](https://pixi.prefix.dev/latest/installation/), then run:
 
 ```bash
-make -C docs setup
-pixi run --locked -e check pre-commit install
+pixi update sequince sequince-density
+pixi install -e default -e docs -e check
+pixi run -e check pre-commit install
 ```
 
 Dependencies, environments, and tasks are defined in `pyproject.toml`.
@@ -82,15 +83,18 @@ Avoid retaining unnecessary histories or adding expensive diagnostics by default
 Before requesting review, run:
 
 ```bash
-make -C docs check
-make -C docs hooks
+pixi run -e check test
+pixi run -e check lint
+pixi run -e check format-check
+pixi run -e check pre-commit run --all-files
 ```
 
-The first command runs pytest, Ruff linting, and formatting checks. Pre-commit
-also checks spelling, whitespace, YAML, and large files, and may modify files.
-Review any edits and rerun the checks. Do not bypass hooks to make commits pass.
-The configurations in `pyproject.toml` and `.pre-commit-config.yaml` are
-authoritative; this repository does not currently configure mypy.
+These commands run pytest, Ruff linting and formatting checks, and pre-commit.
+Pre-commit also checks spelling, whitespace, YAML, and large files, and may
+modify files. Review any edits and rerun the checks. Do not bypass hooks to make
+commits pass. The configurations in `pyproject.toml` and
+`.pre-commit-config.yaml` are authoritative; this repository does not currently
+configure mypy.
 
 Tests live in `tests/`. Test observable behavior and numerical invariants, using
 small fixed inputs or mocked execution for pipeline tests. Some tests require
@@ -106,30 +110,52 @@ directly in the tutorial, with explanations and the relevant source code. The
 reading order in `docs/index.rst` starts with basic examples, then introduces
 other methods, with flow preconditioning before persistent sampling.
 
-Documentation commands run from the repository root:
+Run documentation commands from the repository root. To generate outputs for
+one example, select its declared environment:
 
 ```bash
-make -C docs help
-make -C docs example EXAMPLE=gaussian
-make -C docs example EXAMPLE=flow-preconditioning ENV=flow
-make -C docs examples
-make -C docs docs
-make -C docs docs-only
-make -C docs validate
+pixi run -e default example gaussian
+pixi run -e flow example flow-preconditioning
 ```
 
-`example` runs one manifest entry; `examples` runs all entries sequentially in
-their declared environments. Each execution batch resolves released dependencies
-once and uses the same lock throughout. `docs` refreshes dependencies, reuses
-valid outputs when possible, and executes examples if outputs are missing or
-stale. `docs-only` validates existing outputs and builds Sphinx HTML without
-sampling. `validate` runs checks, reruns all examples, then builds the docs.
-HTML is written to `docs/_build/html/`.
+To run all registered examples sequentially in their declared environments:
 
-Full example execution can consume substantial memory and time. Choose a single
-example when developing, and use `docs-only` when valid results are available.
-Execution has timeouts, but does not currently enforce a memory limit. Do not
-assume that parallel local execution is safe.
+```bash
+pixi run examples
+```
+
+Each execution batch resolves released dependencies once and uses the same lock
+throughout. Full example execution can consume substantial memory and time;
+choose a single example when developing. Execution has timeouts, but does not
+currently enforce a memory limit. Do not assume parallel local execution is safe.
+
+To validate existing outputs, stage the tutorial pages, and build Sphinx HTML:
+
+```bash
+pixi run -e docs docs
+```
+
+Open `docs/_build/html/index.html` in a browser to review the result. This task
+builds with warnings treated as errors and does not execute sampling. Missing or
+stale outputs cause it to stop; regenerate those outputs before building again.
+Pixi may resolve dependencies and update `pixi.lock` before running a task when
+needed.
+
+The Makefile is a standard Sphinx interface, matching Sequince's documentation.
+It supports builders such as `html`, `linkcheck`, and `clean`; `docs` is an alias
+for `html`. It does not install dependencies, run checks, or execute examples.
+To use Make, stage validated outputs first and run it in the docs environment:
+
+```bash
+pixi run -e docs prepare-docs
+pixi run -e docs make -C docs html SPHINXOPTS="-W --keep-going"
+```
+
+Use `pixi run -e docs make -C docs help` to list Sphinx targets. The Pixi `docs`
+task above performs preparation and the HTML build together.
+
+For full validation, run the checks listed above, then run `pixi run examples`
+and `pixi run -e docs docs`, in that order. Stop if any command fails.
 
 ### Adding an example
 
@@ -161,6 +187,14 @@ installs `docs/requirements.txt`, fetches the exact matching bundle, and verifie
 it before building; it does not run sampling. Freshness checks guard `latest`
 builds, and there is no fallback to results from another commit.
 
+Pull requests run examples and build Sphinx at the PR head commit, matching
+Read the Docs previews. After a successful run, the separate
+`Publish PR documentation` workflow runs trusted code from the default branch.
+It reads the completed run's artifact as data, checks its archive and commit,
+publishes it under `docs-pr-<PR-number>-<head-SHA>`, and requests the PR preview.
+PR code and artifacts are never executed in that publishing job. Read the Docs
+then performs the same output provenance validation used for `latest`.
+
 Maintainers must configure the Read the Docs project, the repository variable
 `RTD_PROJECT`, and the secret `RTD_TOKEN` before enabling this hosting workflow.
 Keep credentials out of source files and pull request jobs. The configuration

docs/Makefile

@@ -1,66 +1,22 @@
-.DEFAULT_GOAL := help
+# Minimal makefile for Sphinx documentation
+#
 
-DOCS_DIR := $(abspath $(dir $(lastword $(MAKEFILE_LIST))))
-REPO_ROOT := $(abspath $(DOCS_DIR)/..)
-
-PIXI ?= pixi
-EXAMPLE ?= gaussian
-ENV ?= default
-
-.PHONY: help setup test lint format-check check hooks example examples refresh docs docs-only validate
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
 
+# Put it first so that "make" without argument is like "make help".
 help:
-	@printf '%s\n' \
-	  'make setup         Refresh released dependencies and install environments' \
-	  'make refresh       Resolve released dependencies without sampling' \
-	  'make check         Run tests, lint and formatting checks' \
-	  'make test          Run pipeline tests' \
-	  'make lint          Run Ruff lint checks' \
-	  'make format-check  Check Python formatting' \
-	  'make hooks         Run all pre-commit hooks (may edit files)' \
-	  'make example EXAMPLE=gaussian [ENV=default]' \
-	  '                   Run one example in the selected environment' \
-	  'make examples      Run all documentation examples in their environments' \
-	  'make docs          Reuse valid outputs or run examples, then build docs' \
-	  'make docs-only     Build docs using existing validated outputs' \
-	  'make validate      Run checks, all examples, then build docs'
-
-refresh:
-	cd "$(REPO_ROOT)" && $(PIXI) update sequince sequince-density
-
-setup: refresh
-	cd "$(REPO_ROOT)" && $(PIXI) install --locked -e default -e docs -e check
-
-test:
-	cd "$(REPO_ROOT)" && $(PIXI) run --locked -e check test
-
-lint:
-	cd "$(REPO_ROOT)" && $(PIXI) run --locked -e check lint
-
-format-check:
-	cd "$(REPO_ROOT)" && $(PIXI) run --locked -e check format-check
-
-check: test lint format-check
-
-hooks:
-	cd "$(REPO_ROOT)" && $(PIXI) run --locked -e check pre-commit run --all-files
-
-example:
-	cd "$(REPO_ROOT)" && $(PIXI) run --locked -e $(ENV) example $(EXAMPLE)
-
-examples:
-	cd "$(REPO_ROOT)" && $(PIXI) run --locked examples
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-docs: refresh
-	@if ! (cd "$(REPO_ROOT)" && $(PIXI) run --locked -e docs validate-outputs); then \
-	  $(MAKE) -C "$(DOCS_DIR)" examples || exit $$?; \
-	fi
-	$(MAKE) -C "$(DOCS_DIR)" docs-only
+.PHONY: help docs Makefile
 
-docs-only:
-	cd "$(REPO_ROOT)" && $(PIXI) run --locked -e docs docs
+docs: html
 
-# Keep execution before Sphinx even when invoked with make -j.
-validate: check
-	$(MAKE) -C "$(DOCS_DIR)" examples
-	$(MAKE) -C "$(DOCS_DIR)" docs-only
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/index.rst

@@ -45,5 +45,5 @@ dependencies.
 For background and the full interface reference, see Sequince's
 `user guide <https://sequince.readthedocs.io/en/latest/user_guide.html>`_
 and `API reference <https://sequince.readthedocs.io/en/latest/api/index.html>`_.
-The examples use :external:py:class:`sequince.ParticleState` to represent the
+The examples use :external:py:class:`~sequince.state.ParticleState` to represent the
 weighted particle population.