fix(docs): build subpackage docs from the package directory

[d-v-b]

🤖 AI text below 🤖

The failure

The zarr_indexing-v0.2.0 docs build fails on Read the Docs:

ERROR   -  Error reading page 'index.md': Snippet at path 'snippets/canonical_slice.py' could not be found
pymdownx.snippets.SnippetMissingError: Snippet at path 'snippets/canonical_slice.py' could not be found

The file is not missing. It is at packages/zarr-indexing/docs/snippets/canonical_slice.py, and the build is looking somewhere else.

Cause

pymdownx.snippets resolves a relative base_path against the current working directory, not against the config file. zarr-indexing/mkdocs.yml has:

- pymdownx.snippets:
    base_path: [docs, examples]

and docs/index.md does --8<-- "snippets/canonical_slice.py:landing-quickstart", so the snippet is looked for at <cwd>/docs/snippets/canonical_slice.py:

Build	Working directory	Resolves to
just docs-check, CI	packages/zarr-indexing	packages/zarr-indexing/docs/snippets/…	✅
Read the Docs (-f from the repo root)	repo root	<repo>/docs/snippets/… — zarr-python's core docs	❌

That is why CI is green and Read the Docs is not.

Fix

Build from inside the package instead of pointing -f at its config from the repo root:

-        - mkdocs build --strict -f packages/zarr-indexing/mkdocs.yml --site-dir $READTHEDOCS_OUTPUT/html
+        - cd packages/zarr-indexing && mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html

$READTHEDOCS_OUTPUT is absolute, so the cd does not change where the site lands.

This is preferred over making base_path config-relative, which would also require rewriting every --8<-- path. More importantly it makes the Read the Docs invocation identical to the local and CI ones, so a green just docs-check means a green Read the Docs build — the class of bug goes away rather than this one instance of it.

Scope

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 setting resolved against the working directory, and it would surface only on Read the Docs, after a release.

Verification

• Reproduced the failure against the tagged commit d9af955f in a scratch worktree: building from the repo root with -f fails with the identical error; building from the package directory succeeds.
• All three packages build clean with the new command, and the rendered snippet is present in zarr-indexing's index.html.
• The old command still reproduces SnippetMissingError, confirming the diff is what changes the outcome.

Note

Read the Docs builds tags, so this does not repair the published zarr_indexing-v0.2.0 build. A patch release cut from main after this merges will build correctly.