Skip to content

docs: fix errors and improve consistency across the documentation#4132

Open
d-v-b wants to merge 18 commits into
zarr-developers:mainfrom
d-v-b:claude/zarr-python-docs-review-764989
Open

docs: fix errors and improve consistency across the documentation#4132
d-v-b wants to merge 18 commits into
zarr-developers:mainfrom
d-v-b:claude/zarr-python-docs-review-764989

Conversation

@d-v-b

@d-v-b d-v-b commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

I pointed claude fable at our docs and asked it to look for fixes

A full critical review of the documentation, with every finding verified by executing the runnable snippets against the current source (all tests/test_docs.py pass, strict mkdocs build is clean, and all relative links/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, with a note that serialized layout is governed by codecs.
  • 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 (matches the measured timings the page renders).
  • "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).

Invisible code blocks: three exec="true" blocks without source="above" rendered as nothing in the built site (the rectilinear-chunks enable snippet in arrays.md, and the async.concurrency / threading.max_workers examples in performance.md). All are now visible.

Other errors:

  • storage.md: the explicit-S3-filesystem example passed the bucket's virtual-hosted URL as endpoint_url (which would double the bucket name in request paths) 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.namecodecs.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); the truncated store-table row (a leftover from Improve store section in migration guide #3552) 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; the "equivalent functions" now name migrate_v2_to_v3/remove_metadata.
  • installation.md: typing_extensions minimum corrected to 4.14; all five optional-dependency groups documented (the old text claimed universal_pathlib "must be installed separately" — it's the optional extra).
  • 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".

Usability improvements

  • User Guide nav reordered into a beginner→advanced progression (data types moved next to the core concepts; the v3 migration guide moved out of the middle).
  • quick-start.md: proper H1 and 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 (previously undiscoverable from the guide index).
  • groups.md: explains group/create_group/open_group, and documents member enumeration (keys, members, in) and deletion.
  • attributes.md: documents update_attributes for bulk updates (each single assignment is a separate metadata write), deletion, and links consolidated metadata.
  • consolidated_metadata.md: documents the public use_consolidated=True/False/None knob, including the escape hatch for the staleness caveat.
  • glossary.md: adds Group, Attributes, and Consolidated Metadata entries; the Metadata entry now covers the v2 documents.
  • Cross-links added between related pages throughout; the "Coming soon" stubs (rechunking, Blosc, custom stores) 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.
  • All relative links and anchors mechanically verified.
  • codespell: clean.

🤖 Generated with Claude Code

dependabot Bot and others added 14 commits May 31, 2026 19:28
…#176)

Bumps the actions group with 8 updates in the / directory:

| Package | From | To |
| --- | --- | --- |
| [prefix-dev/setup-pixi](https://github.com/prefix-dev/setup-pixi) | `0.9.5` | `0.9.6` |
| [codecov/codecov-action](https://github.com/codecov/codecov-action) | `6.0.0` | `6.0.1` |
| [github/issue-metrics](https://github.com/github/issue-metrics) | `4.2.2` | `4.2.7` |
| [j178/prek-action](https://github.com/j178/prek-action) | `2.0.3` | `2.0.4` |
| [actions/upload-artifact](https://github.com/actions/upload-artifact) | `7.0.0` | `7.0.1` |
| [actions/download-artifact](https://github.com/actions/download-artifact) | `7.0.0` | `8.0.1` |
| [pypa/gh-action-pypi-publish](https://github.com/pypa/gh-action-pypi-publish) | `1.13.0` | `1.14.0` |
| [zizmorcore/zizmor-action](https://github.com/zizmorcore/zizmor-action) | `0.5.3` | `0.5.6` |



Updates `prefix-dev/setup-pixi` from 0.9.5 to 0.9.6
- [Release notes](https://github.com/prefix-dev/setup-pixi/releases)
- [Commits](prefix-dev/setup-pixi@1b2de7f...5185adf)

Updates `codecov/codecov-action` from 6.0.0 to 6.0.1
- [Release notes](https://github.com/codecov/codecov-action/releases)
- [Changelog](https://github.com/codecov/codecov-action/blob/main/CHANGELOG.md)
- [Commits](codecov/codecov-action@57e3a13...e79a696)

Updates `github/issue-metrics` from 4.2.2 to 4.2.7
- [Release notes](https://github.com/github/issue-metrics/releases)
- [Commits](github-community-projects/issue-metrics@c9e9838...1e38d5e)

Updates `j178/prek-action` from 2.0.3 to 2.0.4
- [Release notes](https://github.com/j178/prek-action/releases)
- [Commits](j178/prek-action@6ad8027...bdca6f1)

Updates `actions/upload-artifact` from 7.0.0 to 7.0.1
- [Release notes](https://github.com/actions/upload-artifact/releases)
- [Commits](actions/upload-artifact@v7...043fb46)

Updates `actions/download-artifact` from 7.0.0 to 8.0.1
- [Release notes](https://github.com/actions/download-artifact/releases)
- [Commits](actions/download-artifact@v7...3e5f45b)

Updates `pypa/gh-action-pypi-publish` from 1.13.0 to 1.14.0
- [Release notes](https://github.com/pypa/gh-action-pypi-publish/releases)
- [Commits](pypa/gh-action-pypi-publish@v1.13.0...cef2210)

Updates `zizmorcore/zizmor-action` from 0.5.3 to 0.5.6
- [Release notes](https://github.com/zizmorcore/zizmor-action/releases)
- [Commits](zizmorcore/zizmor-action@b1d7e1f...5f14fd0)

---
updated-dependencies:
- dependency-name: prefix-dev/setup-pixi
  dependency-version: 0.9.6
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: actions
- dependency-name: codecov/codecov-action
  dependency-version: 6.0.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: actions
- dependency-name: github/issue-metrics
  dependency-version: 4.2.7
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: actions
- dependency-name: j178/prek-action
  dependency-version: 2.0.4
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: actions
- dependency-name: actions/upload-artifact
  dependency-version: 7.0.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: actions
- dependency-name: actions/download-artifact
  dependency-version: 8.0.1
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: actions
- dependency-name: pypa/gh-action-pypi-publish
  dependency-version: 1.14.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: actions
- dependency-name: zizmorcore/zizmor-action
  dependency-version: 0.5.6
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: actions
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
A full review of the documentation, verified by executing every runnable
snippet against the current source. Highlights:

Correctness:
- performance.md: fix three claims contradicted by the page's own rendered
  output (memory-order/compression, inverted write_empty_chunks conclusion,
  wrong async.concurrency and threading.max_workers defaults); update stale
  MemoryStore pickle claim
- Make three invisible exec blocks visible (rectilinear enable snippet in
  arrays.md, two config snippets in performance.md)
- storage.md: fix the explicit-S3-filesystem example (endpoint_url misuse,
  missing bucket path)
- config.md: show true defaults (earlier example no longer leaks array.order
  into the session); fix codecs.bytes key
- arrays.md: document all five ArrayConfig options; correct memory:// store
  description; fix wrong column-index comments; remove orphaned example
- v3_migration.md: remove Group.move and dimension_separator from
  not-yet-ported lists (both work); fix truncated store table row; update
  lapsed 2.x support-window and stale work-in-progress framing
- cli.md: document the required cli extra; fix dry-run output; name the
  equivalent functions in zarr.metadata.migrate_v3
- installation.md: correct typing_extensions minimum; document all optional
  dependency groups (remote, gpu, cli, optional, cast-value-rs)
- gpu.md: fix nonexistent zarr.Config.enable_gpu; add installation guidance
- contributing.md: fix docs build output dir and serve URL; drop outdated
  doctest note
- extending.md: custom data types are supported now, not future work
- data_types.md: remove stray doctest output from a source block; use public
  zarr.dtype import; drop dead warnings-suppression boilerplate
- quick-start.md: fix result="html" on a Python-repr output block

Usability:
- Reorder the user-guide nav into a beginner-to-advanced progression
- quick-start.md: add H1 and heading hierarchy, remote-storage install note,
  and a Next steps section
- user-guide/index.md: list the CLI, experimental, and examples pages
- groups.md: explain group/create_group/open_group; document member
  enumeration and deletion
- attributes.md: document bulk updates via update_attributes and deletion
- consolidated_metadata.md: document the public use_consolidated knob
- glossary.md: add Group, Attributes, and Consolidated Metadata entries;
  cover v2 metadata documents
- Add cross-links between related pages throughout; replace "Coming soon"
  stubs with links to existing content
- experimental.md: nest CacheStore sections properly; link the experimental
  API policy
- release-notes.md: normalize version headings and dates

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@github-actions github-actions Bot added the needs release notes Automatically applied to PRs which haven't added release notes label Jul 8, 2026
@github-actions github-actions Bot removed the needs release notes Automatically applied to PRs which haven't added release notes label Jul 8, 2026
@d-v-b

d-v-b commented Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant