Skip to content

fix(docs): build subpackage docs from the package directory - #4252

Merged
d-v-b merged 1 commit into
zarr-developers:mainfrom
d-v-b:claude/fix-rtd-docs-cwd
Aug 12, 2026
Merged

fix(docs): build subpackage docs from the package directory#4252
d-v-b merged 1 commit into
zarr-developers:mainfrom
d-v-b:claude/fix-rtd-docs-cwd

Conversation

@d-v-b

@d-v-b d-v-b commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

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

  • I am a human, these are my changes, and I have reviewed and understood every change and can explain why each is correct.

TODO

  • Add unit tests and/or doctests in docstrings
  • Add docstrings and API docs for any new/modified user-facing classes and functions
  • New/modified features documented in docs/user-guide/*.md
  • Changes documented as a new file in changes/
  • GitHub Actions have all passed
  • Test coverage is 100% (Codecov passes)

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
@github-actions github-actions Bot added the needs release notes Automatically applied to PRs which haven't added release notes label Aug 12, 2026
@d-v-b
d-v-b marked this pull request as ready for review August 12, 2026 14:12
@d-v-b

d-v-b commented Aug 12, 2026

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.

@d-v-b
d-v-b merged commit 5b9c09f into zarr-developers:main Aug 12, 2026
52 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs release notes Automatically applied to PRs which haven't added release notes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant