docs: fix errors and improve consistency across the documentation

[d-v-b]

🤖 AI text below 🤖

A full critical review of the documentation with every finding verified by executing the runnable snippets against the current source, followed by a series of rendering and navigation improvements. All tests/test_docs.py pass, strict mkdocs build is clean, and all relative links and anchors were mechanically checked.

Correctness fixes

performance.md had three claims contradicted by the page's own live-rendered output:

• The memory-order example claimed "Fortran order gives a better compression ratio" — in Zarr format 3, order affects in-memory layout only; stored bytes are identical (verified: both orders stored byte-identical data). The section is rewritten around what order actually does.
• The write_empty_chunks conclusion was inverted: the emptiness check runs when the flag is False, so random-data writes are slower with False, not True.
• "Zarr's default concurrency of 64" → 10 (and the dependent arithmetic), and threading.max_workers "defaults to CPU count" → None; both now consistent with the correct statements earlier on the same page.
• The stale "MemoryStore cannot be pickled" claim is replaced with the real caveat (pickling copies the data).

Other errors:

• storage.md: the explicit-S3-filesystem example passed the bucket's virtual-hosted URL as endpoint_url and pointed FsspecStore at the filesystem root; now a correct copyable pattern.
• config.md: the "current default configuration" block showed order: 'F' because an earlier snippet in the same build session mutated the config; also codecs.bytes.name → codecs.bytes.
• arrays.md: "three configuration options" → all five ArrayConfig fields documented; memory:// URLs were attributed to MemoryStore (they resolve to an fsspec-backed store when fsspec is installed); wrong column indices in two comments; stray doctest-output line removed from data_types.md.
• v3_migration.md: Group.move and dimension_separator removed from the "not yet ported" lists (both are implemented); a truncated store-table row removed; the lapsed 2.x support window rewritten in past tense; the "🚧 Work in Progress 🚧" framing updated to 3.2.x reality.
• cli.md: the zarr[cli] extra is now documented (a plain install crashes with ModuleNotFoundError); the dry-run example output corrected to the real file:// form.
• installation.md: typing_extensions minimum corrected to 4.14; all five optional-dependency groups documented.
• gpu.md: zarr.Config.enable_gpu (nonexistent) → zarr.config.enable_gpu(); installation guidance added.
• contributing.md: docs build output is site/, not docs/_build/html; serve URL corrected; outdated doctest note removed.
• extending.md: custom data types are supported today (links to the dtype guide and worked example), not "in the future".
• quick-start.md: result="html" on a Python-repr block → result="code".
• Standardized on American spelling in living prose (behaviour → behavior).

Rendering fixes

• New MkDocs hook (mkdocs_hooks.py): fences marked test="true" or exec="false" (the repo's docs-validation convention) failed superfences parsing entirely and spilled their contents into the page as raw markdown — most visibly the custom dtype example, where the included script's PEP 723 header rendered as a cascade of headings. The GPU page, quick-start S3 example, and all exec="false" opt-outs were equally affected. The hook registers a second python fence, tried when Markdown Exec's declines, that renders these as ordinary highlighted code blocks.
• Invisible code blocks: three exec="true" blocks without source="above" rendered as nothing (the rectilinear-chunks enable snippet in arrays.md, and two config snippets in performance.md). All are now visible.
• data_types.md: two blocks lacked result formatting and injected their output as raw paragraphs.

Examples

• Rectilinear chunks: converted from a mkdocs-jupyter notebook (which rendered its PEP 723 header as a code cell, leaked a ConfigSet repr, and didn't match the site style) to a markdown page in the same style as the custom dtype example, with captured outputs as static blocks and an admonition explaining the xarray-fork requirement. Page URL unchanged. With no notebooks left, the mkdocs-jupyter plugin and dependency are removed.
• Custom dtype example: title shortened to "Custom Data Type"; README now leads with uv run (PEP 723) since plain python fails without deps installed.

API reference navigation

• One nav entry per object, mirroring the flat zarr namespace: the create/open/save/load pages grouped functions by verb — an organization that doesn't exist in the codebase. Each of the 26 top-level functions now has its own page (api/zarr/functions/<name>.md) and nav entry, alphabetized case-insensitively alongside the classes and modules, so zarr.Array (class) sits next to zarr.array (function). Old URLs redirect.
• Kind badges: every API nav entry shows the compact func/mod/class doc-symbol badge that mkdocstrings already uses in each page's table of contents, and identifiers render in monospace. Verified in the rendered site: no wrapped entries, badge CSS loads globally.
• Previously undocumented public functions added to the reference: zarr.consolidate_metadata and zarr.print_debug_info. The unimplemented copy/copy_all/copy_store stubs and deprecated zarr.tree are deliberately excluded.
• Fixed accidental nav labels: two literal "Index" entries, an "API" section nested under "API Reference", title-cased "Cpu"/"Gpu", and ambiguous twin "metadata" entries.

Usability improvements

• User Guide nav reordered into a beginner→advanced progression.
• quick-start.md: proper heading hierarchy, zarr[remote] note for the cloud example, and a "Next steps" section.
• user-guide/index.md now lists the CLI, experimental-features, and examples pages.
• groups.md: explains group/create_group/open_group; documents member enumeration and deletion.
• attributes.md: documents update_attributes for bulk updates, deletion, and links consolidated metadata.
• consolidated_metadata.md: documents the public use_consolidated=True/False/None knob.
• glossary.md: adds Group, Attributes, and Consolidated Metadata entries; covers v2 metadata documents.
• Cross-links added between related pages throughout; "Coming soon" stubs replaced with links to existing content.
• experimental.md: CacheStore sections properly nested; links the experimental API policy.
• release-notes.md: version headings and dates normalized.

Verification

• tests/test_docs.py: 57 passed, 2 skipped (GPU/cupy and a known skip).
• mkdocs build --strict: clean (validates every mkdocstrings directive and redirect target).
• All relative links and anchors mechanically verified; codespell clean.
• Nav and badge rendering verified by serving the built site and inspecting the DOM.

🤖 Generated with Claude Code

[d-v-b]

@zarr-developers/python-core-devs this is a big, flat, boring collection of AI-authored changes to our docs. If anyone wants to spot-check it, please have a look. Otherwise, I'm going to review everything by hand, and then merge shortly.

[d-v-b]

removed a dead cell

[d-v-b]

this example is redundant. we show None = no compression earlier.

[d-v-b]

this example has nothing to do with block indexing

[d-v-b]

updated the API navbar from this:

to this:

[d-v-b]

I'm going to self-merge, these are all safe, minor improvements or corrections to the docs.

[maxrjones]

Hey, @d-v-b, I really appreciate your work improving our documentation. I'd like to suggest a couple process-based improvements. I'd be grateful if you take these requests in a way that doesn't devalue your overall work, which is keeping Zarr-Python moving forward and incredible valuable.

updated the API navbar from this:

to this:

I think this an acceptable change, but out of scope from "fix errors and improve consistency across the documentation". I would prefer that PRs remain neatly scoped. Taking this as an example, others could tune in to a PR with a description "docs: update API documentation TOC" if they care, whereas they may have unsubscribed already from this PR.

I think it's important for core devs to follow our contributing policies, or open a PR to change them. The relevant parts for this PR include:

• PR descriptions being written by a human
• The human having reviewed all changed before opening the PR

[d-v-b]

Thanks for the feedback max! My judgement was that changing the navbar to consistently class / function labels for all the contents was a safe fix, since it doesn't affect URLs and the old navbar was confusing in a way that seemed unintentional.

But I would be very surprised if anyone particularly interested in any specific part of the docs would tune in to this PR on the basis of its title -- this PR is tranche of unrelated fixes scattered across the docs, which is only possible because LLMs can translate prompts like "review our docs, find errors and opportunities for improvement" into concrete changes. Ideally these prompts result in the LLM finding no problems, but until then, I do think this is an efficient way to surface problems and fix them. This of course relies heavily on our judgment as maintainers -- I would only open a PR like this in a repo I am maintaining, and docs changes won't affect runtime behavior, and the docs are not turing complete, at least not how we use them, so changes don't interact, and a lot of changes are safe in one go.

Which brings me to the second point: if we accept that PRs like this have value (happy to discuss this but I think doing these changes in 1 PR is far more efficient than opening separate PRs for each change), then requiring a human-authored PR description feels like a waste of time. At this point, I view a PR like this (administered by someone very familiar with the codebase) as not so different from a dependabot PR. We don't require dependabot PR descriptions to be written by humans. Instead, we require the consequences of dependabot PRs to be owned by humans. So I wonder if we should either revise the "human-authored PR description" requirement, or introduce a mechanism for explicitly LLM-authored PRs, like dependabot PRs. I am not using LLM text here because I want to cheat the system and boost my credentials, i'm just busy and the LLM writes PR descriptions more consistently and exhaustively than I do.

[maxrjones]

Thanks for the feedback max! My judgement was that changing the navbar to consistently class / function labels for all the contents was a safe fix, since it doesn't affect URLs and the old navbar was confusing in a way that seemed unintentional.

But I would be very surprised if anyone particularly interested in any specific part of the docs would tune in to this PR on the basis of its title -- this PR is tranche of unrelated fixes scattered across the docs, which is only possible because LLMs can translate prompts like "review our docs, find errors and opportunities for improvement" into concrete changes. Ideally these prompts result in the LLM finding no problems, but until then, I do think this is an efficient way to surface problems and fix them. This of course relies heavily on our judgment as maintainers -- I would only open a PR like this in a repo I am maintaining, and docs changes won't affect runtime behavior, and the docs are not turing complete, at least not how we use them, so changes don't interact, and a lot of changes are safe in one go.

Which brings me to the second point: if we accept that PRs like this have value (happy to discuss this but I think doing these changes in 1 PR is far more efficient than opening separate PRs for each change), then requiring a human-authored PR description feels like a waste of time. At this point, I view a PR like this (administered by someone very familiar with the codebase) as not so different from a dependabot PR. We don't require dependabot PR descriptions to be written by humans. Instead, we require the consequences of dependabot PRs to be owned by humans. So I wonder if we should either revise the "human-authored PR description" requirement, or introduce a mechanism for explicitly LLM-authored PRs, like dependabot PRs. I am not using LLM text here because I want to cheat the system and boost my credentials, i'm just busy and the LLM writes PR descriptions more consistently and exhaustively than I do.

It sounds like you prefer the option from my earlier comment of changing the contributing guide (possibly through an exclusion for core developers). That's alright with me. There's a very minimal subset of our guide that I actually care strongly about for core devs, beyond the obvious understanding/agreeing with/owning the changes:

• meaningful commit messages our git history, in particular the one-liners. I feel strongly that a view of https://github.com/zarr-developers/zarr-python/commits/main/ should signal high-quality, thoughtful development.
• having at minimum the start of a PR description being written by a human, regardless of whether it's internally/externally authored. I think writing one sentence about why you think its worth prompting an agent, spending time reviewing/owning the PR, and adding it to other's feed (via pre-release reviews at this point). I think this is a super low bar of additional work over reviewing/owning a set of AI written changing.

[d-v-b]

sounds good, I'll open a PR to update the developer guide