🧪 TEST: re-read mounted docs when their files/include targets change#10
Merged
Merged
Conversation
Lock in Sphinx's incremental-rebuild behaviour for mounted content. No production code is touched — these are regression tests proving detection rides on the absolute external paths the mounter records in Project._docname_to_path and env.dependencies. Two change-detection paths are covered: - A file-list-mounted doc whose own source is edited is re-read (parity with the existing directory-mount coverage). - A mounted doc whose *referenced* file changes — while the doc's own source is untouched — is re-read via the dependency-mtime check, across every file-referencing directive: literalinclude, include, csv-table :file:, raw :file:, image, figure, graphviz, uml, mermaid. Each directive case asserts the target is recorded as an external dependency (precondition) before asserting the re-read, so the signal cannot be a false positive.
Merged
ubmarco
added a commit
that referenced
this pull request
Jun 14, 2026
Bump version 0.1.0 → 0.1.1 (pyproject.toml, package __version__, and the uv.lock self-entry) and stamp the accumulated Unreleased changelog entries as the 0.1.1 release, dated 2026-06-14: - per-mount path_check option for mounted-bundle path confinement (#7) - regression coverage proving absolute diagnostic locations for mounted docs (#9) - regression coverage proving incremental rebuilds re-read mounted docs when their files / include targets change (#10) - CI matrix extended to cover Sphinx 8 on Python 3.12 — full 7/8/9 coverage on py312 (#11)
ubmarco
added a commit
that referenced
this pull request
Jun 14, 2026
## Release 0.1.1 Version bump `0.1.0 → 0.1.1` plus changelog stamp. No library code changes — this is release-prep only. ### Changes - `pyproject.toml` + `src/sphinx_mounts/__init__.py`: version `0.1.0 → 0.1.1` - `uv.lock`: own-package version synced to `0.1.1` - `docs/source/changelog.rst`: the accumulated `Unreleased` entries are stamped as the `0.1.1` release (dated 2026-06-14), matching the `0.1.0` block's format (label + `:Released:`), with no empty `Unreleased` section left behind — same convention the `0.1.0` tag used. ### Included in 0.1.1 - **Per-mount `path_check`** option (`"error"` default / `"warn"` / `"off"`) that confines mounted-bundle directives to the bundle root (#7) - Regression coverage proving **absolute diagnostic locations** for mounted docs (#9) - Regression coverage proving **incremental rebuilds re-read** mounted docs when their files / include targets change (#10) - **Sphinx 8 CI coverage** — the matrix now exercises Sphinx 8 on Python 3.12 (full 7/8/9 coverage) (#11) ### Intentionally excluded from the changelog - **#6 (`html_extra_path` example)** — the commit itself notes this is stock Sphinx composing with mounts, *not* a sphinx-mounts feature; only `tests/example/` + `tests/` changed, no `src/`. - **#8** — CI-only (Bazel doc-build wiring). - **#4** — docs-site sidebar link (cosmetic). ### Verification - `uv run prek run` — all hooks pass (the CI `Prek` gate) - `uvx ruff@0.12.2 format --check` — already formatted (CI's pinned ruff) - `sphinx-build -nW --keep-going` — docs build succeeds; changelog renders ### After merge Publishing is tag-driven (PyPI Trusted Publishing via `release.yaml`). To cut the release: ```bash git tag -a 0.1.1 -m "Release 0.1.1" git push origin 0.1.1 ``` The bare-semver tag (`0.1.1`, no `v`) matches the workflow trigger and publishes to PyPI.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Regression tests locking in Sphinx's incremental-rebuild behaviour for
mounted content: a change to a mounted document's files leads to a
re-read on the next build. No production code is touched — detection
already rides on the absolute external paths the mounter records in
Project._docname_to_pathandenv.dependencies, which Sphinx stats oneach build. These tests prove and pin that down where it had no coverage.
Coverage added
Two distinct change-detection paths:
(
test_incremental_rereads_changed_file_in_file_list_mount) — paritywith the existing directory-mount coverage, which only exercised
directory mode.
untouched → re-read via the dependency-mtime path, across every
file-referencing directive the repo supports
(
test_changed_include_target_rereads_mounted_doc, parametrised):literalinclude,include,csv-table :file:,raw :file:,image,figure,graphviz,uml,mermaid.Each directive case first asserts its target is recorded as an external
dependency of the mounted doc (precondition), so a passing re-read cannot
be a false positive. Teeth were verified during development with a
throwaway no-change control across all nine directives (no change → no
re-read); it is not part of the committed suite.
The diagram directives stay renderer-independent (mermaid
rawoutput;graphviz/uml assert via the recorded dependency), so no
dot/java/mmdcbinary is required — matching the existing path-directive tests.
Checklist
test_mounting.py, 9 parametrised intest_path_directives.py). Full suite: 156 passed.docs/source/updates needed.docs/source/changelog.rstupdated (Unreleased).uv run prek run --all-filespasses;ruff@0.12.2format/lint clean on the pinned version.