fix(docs): build subpackage docs from the package directory - #4252
Merged
Conversation
Read the Docs pointed `-f` at each package's mkdocs.yml from the repo root. mkdocs resolves some settings relative to the current working directory rather than to the config file, so building from elsewhere looks for them in the wrong place -- and silently, because the paths are valid, just wrong. zarr-indexing hit this at v0.2.0: `pymdownx.snippets` has a relative `base_path` of `[docs, examples]`, so `--8<-- "snippets/canonical_slice.py"` resolved against the repo root and searched zarr-python's own docs/ rather than the package's. The build failed with SnippetMissingError while `just docs-check` passed, because that runs from the package directory. Building from the package directory makes the Read the Docs invocation identical to the local and CI ones, so a green build there means a green build here. $READTHEDOCS_OUTPUT is absolute, so the cd does not affect where the site lands. Applied to all three packages. Only zarr-indexing is failing today; zarr-metadata and zarr-http-server do not use snippets, so for them this is preventive -- the hazard is any config resolved against the working directory, and it would show up only on Read the Docs. Assisted-by: ClaudeCode:claude-opus-5
d-v-b
marked this pull request as ready for review
August 12, 2026 14:12
Contributor
Author
|
I'm self-merging this as soon as it's green because we need this fix for |
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
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.
My description: this unbreaks docs builds for subpackages by ensuring that RTD builds in the subpackage directory. Claude wrote the fix.
AI description:
Read the Docs pointed
-fat each package's mkdocs.yml from the repo root. mkdocs resolves some settings relative to the current working directory rather than to the config file, so building from elsewhere looks for them in the wrong place -- and silently, because the paths are valid, just wrong.zarr-indexing hit this at v0.2.0:
pymdownx.snippetshas a relativebase_pathof[docs, examples], so--8<-- "snippets/canonical_slice.py"resolved against the repo root and searched zarr-python's own docs/ rather than the package's. The build failed with SnippetMissingError whilejust docs-checkpassed, because that runs from the package directory.Building from the package directory makes the Read the Docs invocation identical to the local and CI ones, so a green build there means a green build here. $READTHEDOCS_OUTPUT is absolute, so the cd does not affect where the site lands.
Applied to all three packages. Only zarr-indexing is failing today; zarr-metadata and zarr-http-server do not use snippets, so for them this is preventive -- the hazard is any config resolved against the working directory, and it would show up only on Read the Docs.
Assisted-by: ClaudeCode:claude-opus-5
For reviewers
[What would you most value a second look at? What are you already confident in? For a refactor, say whether behavior is meant to be unchanged.]
Author attestation
TODO
docs/user-guide/*.mdchanges/