From be229ce116e7198fdf2a1fe3e7929f1ad972c4a5 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Wed, 12 Aug 2026 16:05:39 +0200 Subject: [PATCH] fix(docs): build subpackage docs from the package directory 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 --- packages/zarr-http-server/.readthedocs.yaml | 15 ++++++++++++++- packages/zarr-indexing/.readthedocs.yaml | 15 ++++++++++++++- packages/zarr-metadata/.readthedocs.yaml | 15 ++++++++++++++- 3 files changed, 42 insertions(+), 3 deletions(-) diff --git a/packages/zarr-http-server/.readthedocs.yaml b/packages/zarr-http-server/.readthedocs.yaml index 62a1e82b77..efbda6852d 100644 --- a/packages/zarr-http-server/.readthedocs.yaml +++ b/packages/zarr-http-server/.readthedocs.yaml @@ -24,7 +24,20 @@ build: - pip install ./packages/zarr-http-server --group packages/zarr-http-server/pyproject.toml:docs build: html: - - mkdocs build --strict -f packages/zarr-http-server/mkdocs.yml --site-dir $READTHEDOCS_OUTPUT/html + # Build from inside the package rather than pointing `-f` at its config + # 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, since + # the paths are valid, just wrong. zarr-indexing hit this: with + # `pymdownx.snippets` and a relative `base_path`, its snippets were + # searched for under the repo-root docs/ and the build failed with + # SnippetMissingError, while `just docs-check` passed because it runs + # from here. Building from the package directory makes this identical to + # the local and CI invocations, so a green build there means a green + # build here. + # + # $READTHEDOCS_OUTPUT is absolute, so the cd does not affect it. + - cd packages/zarr-http-server && mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html mkdocs: configuration: packages/zarr-http-server/mkdocs.yml diff --git a/packages/zarr-indexing/.readthedocs.yaml b/packages/zarr-indexing/.readthedocs.yaml index b8c7b76e2b..c1925182f7 100644 --- a/packages/zarr-indexing/.readthedocs.yaml +++ b/packages/zarr-indexing/.readthedocs.yaml @@ -24,7 +24,20 @@ build: - pip install ./packages/zarr-indexing --group packages/zarr-indexing/pyproject.toml:docs build: html: - - mkdocs build --strict -f packages/zarr-indexing/mkdocs.yml --site-dir $READTHEDOCS_OUTPUT/html + # Build from inside the package rather than pointing `-f` at its config + # 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, since + # the paths are valid, just wrong. zarr-indexing hit this: with + # `pymdownx.snippets` and a relative `base_path`, its snippets were + # searched for under the repo-root docs/ and the build failed with + # SnippetMissingError, while `just docs-check` passed because it runs + # from here. Building from the package directory makes this identical to + # the local and CI invocations, so a green build there means a green + # build here. + # + # $READTHEDOCS_OUTPUT is absolute, so the cd does not affect it. + - cd packages/zarr-indexing && mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html mkdocs: configuration: packages/zarr-indexing/mkdocs.yml diff --git a/packages/zarr-metadata/.readthedocs.yaml b/packages/zarr-metadata/.readthedocs.yaml index ace6ccddfd..828773818c 100644 --- a/packages/zarr-metadata/.readthedocs.yaml +++ b/packages/zarr-metadata/.readthedocs.yaml @@ -24,7 +24,20 @@ build: - pip install ./packages/zarr-metadata --group packages/zarr-metadata/pyproject.toml:docs build: html: - - mkdocs build --strict -f packages/zarr-metadata/mkdocs.yml --site-dir $READTHEDOCS_OUTPUT/html + # Build from inside the package rather than pointing `-f` at its config + # 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, since + # the paths are valid, just wrong. zarr-indexing hit this: with + # `pymdownx.snippets` and a relative `base_path`, its snippets were + # searched for under the repo-root docs/ and the build failed with + # SnippetMissingError, while `just docs-check` passed because it runs + # from here. Building from the package directory makes this identical to + # the local and CI invocations, so a green build there means a green + # build here. + # + # $READTHEDOCS_OUTPUT is absolute, so the cd does not affect it. + - cd packages/zarr-metadata && mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html mkdocs: configuration: packages/zarr-metadata/mkdocs.yml