docs(subpackages): render subpackage changelogs as docs pages (#4311)

* docs(zarr-indexing): render the changelog as a docs page

The sidebar and landing page linked to CHANGELOG.md on the GitHub main
branch, so the docs for any version showed the changelog of main. Add
docs/release-notes.md, which includes CHANGELOG.md via pymdownx.snippets
with the package root appended to base_path. The root file stays where
towncrier, PyPI, and GitHub expect it, and each docs build now renders
the release notes for its own version.

The page is named release-notes.md rather than changelog.md because on
a case-insensitive filesystem the latter shadows CHANGELOG.md and the
include resolves to the page itself.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(zarr-indexing): add changelog fragment for #4311

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(zarr-indexing): fix stale page name in mkdocs comment

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(zarr-metadata,zarr-http-server): render the changelog as a docs page

Same change as for zarr-indexing: the sidebar and landing page linked to
CHANGELOG.md on the GitHub main branch, so the docs for any version
showed the changelog of main. Add docs/release-notes.md, which includes
CHANGELOG.md via pymdownx.snippets with the package root in base_path.
Neither package had the snippets extension enabled, so it is added with
check_paths so an unresolved include fails the build.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: d-v-b

packages/zarr-http-server/changes/4311.doc.md

@@ -0,0 +1,2 @@
+The docs now render the release notes as a page instead of linking to
+`CHANGELOG.md` on GitHub, so each docs version shows its own changelog.

packages/zarr-http-server/docs/index.md

@@ -67,5 +67,5 @@ Reads are all that is enabled by default: `GET` and `HEAD` are served, and
 - [User guide](guide.md) — building apps, running them, byte ranges, CORS,
   writes, notebooks, and Uvicorn configuration
 - [API reference](api/index.md)
-- [Changelog](https://github.com/zarr-developers/zarr-python/blob/main/packages/zarr-http-server/CHANGELOG.md)
+- [Release notes](release-notes.md)
 - [License (MIT)](https://github.com/zarr-developers/zarr-python/blob/main/packages/zarr-http-server/LICENSE.txt)

packages/zarr-http-server/docs/release-notes.md

@@ -0,0 +1,8 @@
+<!-- CHANGELOG.md at the package root is the single source of truth: towncrier
+     writes releases into it, and PyPI and GitHub render it directly. This page
+     includes it so each docs build shows the release notes for its own version.
+     The page is not named changelog.md on purpose: on a case-insensitive
+     filesystem that name shadows CHANGELOG.md and the include resolves to the
+     page itself. -->
+
+--8<-- "CHANGELOG.md"

packages/zarr-http-server/mkdocs.yml

@@ -16,7 +16,7 @@ nav:
   - guide.md
   - API Reference:
       - api/index.md
-  - Changelog: https://github.com/zarr-developers/zarr-python/blob/main/packages/zarr-http-server/CHANGELOG.md
+  - Release notes: release-notes.md
 
 watch:
   - src
@@ -98,3 +98,11 @@ markdown_extensions:
       line_spans: __span
       pygments_lang_class: true
   - pymdownx.inlinehilite
+  - pymdownx.snippets:
+      # The package root lets docs/release-notes.md include the
+      # towncrier-managed CHANGELOG.md without moving it out of the package
+      # root, where PyPI and GitHub readers expect it.
+      base_path: [docs, .]
+      # Fail the build on an unresolvable include instead of silently
+      # rendering nothing.
+      check_paths: true

packages/zarr-indexing/changes/4311.doc.md

@@ -0,0 +1,2 @@
+The docs now render the release notes as a page instead of linking to
+`CHANGELOG.md` on GitHub, so each docs version shows its own changelog.

packages/zarr-indexing/docs/index.md

@@ -49,5 +49,5 @@ the chain stays one description, and where the materialization boundary is.
 - [Design notes](design-notes.md) — TensorStore lineage, box vs query, and
   deliberate limits.
 - [API reference](api/index.md)
-- [Changelog](https://github.com/zarr-developers/zarr-python/blob/main/packages/zarr-indexing/CHANGELOG.md)
+- [Release notes](release-notes.md)
   · [License (MIT)](https://github.com/zarr-developers/zarr-python/blob/main/packages/zarr-indexing/LICENSE.txt)

packages/zarr-indexing/docs/release-notes.md

@@ -0,0 +1,8 @@
+<!-- CHANGELOG.md at the package root is the single source of truth: towncrier
+     writes releases into it, and PyPI and GitHub render it directly. This page
+     includes it so each docs build shows the release notes for its own version.
+     The page is not named changelog.md on purpose: on a case-insensitive
+     filesystem that name shadows CHANGELOG.md and the include resolves to the
+     page itself. -->
+
+--8<-- "CHANGELOG.md"

packages/zarr-indexing/mkdocs.yml

@@ -23,7 +23,7 @@ validation:
     omitted_files: warn
 
 # Top-level rank is consistent: collections (Guide, Examples, API Reference)
-# and standalone artifacts (landing, ndsel spec, design notes, changelog).
+# and standalone artifacts (landing, ndsel spec, design notes, release notes).
 # Guide mirrors the docs/guide/ directory — its three pages are one
 # collection (learn / look up / integrate), pydantic's Concepts pattern at
 # small scale; navigation.indexes makes the Guide entry itself land on the
@@ -56,7 +56,7 @@ nav:
       - '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code> <code>zarr_indexing.errors</code>': api/errors.md
       - '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code> <code>zarr_indexing.testing.stateful</code>': api/testing_stateful.md
       - '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code> <code>zarr_indexing.testing.strategies</code>': api/testing_strategies.md
-  - Changelog: https://github.com/zarr-developers/zarr-python/blob/main/packages/zarr-indexing/CHANGELOG.md
+  - Release notes: release-notes.md
   # This site is a Read the Docs subproject of zarr-python; give readers a way
   # back to the parent docs, which list every companion package.
   - 'zarr-python ↪': https://zarr.readthedocs.io/
@@ -148,7 +148,10 @@ markdown_extensions:
   - pymdownx.tabbed:
       alternate_style: true
   - pymdownx.snippets:
-      base_path: [docs, examples]
+      # The package root is last so docs/release-notes.md can include the
+      # towncrier-managed CHANGELOG.md without moving it out of the package
+      # root, where PyPI and GitHub readers expect it.
+      base_path: [docs, examples, .]
       # Fail the build on an unresolvable include or missing region instead
       # of silently rendering nothing. tests/test_doc_examples.py mirrors
       # base_path when it verifies the include graph.

packages/zarr-indexing/tests/test_doc_examples.py

@@ -44,7 +44,7 @@
 
 # Mirrors `pymdownx.snippets: base_path` in mkdocs.yml. If that list changes,
 # change this one in the same commit.
-SNIPPET_BASE_PATHS = (DOCS, STANDALONE_EXAMPLES)
+SNIPPET_BASE_PATHS = (DOCS, STANDALONE_EXAMPLES, PACKAGE_ROOT)
 
 _INCLUDE = re.compile(r'--8<--\s+"(?P<target>[^":\n]+?)(?::(?P<region>[^"\n]+))?"')
 

packages/zarr-metadata/changes/4311.doc.md

@@ -0,0 +1,2 @@
+The docs now render the release notes as a page instead of linking to
+`CHANGELOG.md` on GitHub, so each docs version shows its own changelog.