fix(docs): build subpackage docs from the package directory - #4252
Merged
d-v-b merged 1 commit intoAug 12, 2026
Merged
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
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
Copy link
Copy Markdown
Contributor
Author
|
I'm self-merging this as soon as it's green because we need this fix for zarr-indexing docs builds. |
Sorry, something went wrong.
d-v-b
added a commit
to d-v-b/zarr-python
that referenced
this pull request
Aug 16, 2026
Model the setup on zarr-metadata. The package already carried an RTD config, but with the pre-zarr-developers#4252 build command that points `-f` at the config from the repo root; mkdocs resolves some settings relative to the working directory, so that silently looks for them in the wrong place. Build from the package directory instead, making the RTD build identical to `just docs-check` and the CI job. Register the package in the root docs subprojects grid and the README sub-package list, alongside the other companion packages. Assisted-by: ClaudeCode:claude-fable-5
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.
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 -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
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