docs: fix errors and improve consistency across the documentation#4132
Open
d-v-b wants to merge 18 commits into
Open
docs: fix errors and improve consistency across the documentation#4132d-v-b wants to merge 18 commits into
d-v-b wants to merge 18 commits into
Conversation
…#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>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…b.com/d-v-b/zarr-python into claude/zarr-python-docs-review-764989
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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.pypass, strictmkdocs buildis 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:
orderaffects in-memory layout only; stored bytes are identical (verified: both orders stored byte-identical data). The section is rewritten around whatorderactually does, with a note that serialized layout is governed by codecs.write_empty_chunksconclusion was inverted: the emptiness check runs when the flag isFalse, so random-data writes are slower withFalse, notTrue(matches the measured timings the page renders).threading.max_workers"defaults to CPU count" →None; both now consistent with the correct statements earlier on the same page.Invisible code blocks: three
exec="true"blocks withoutsource="above"rendered as nothing in the built site (the rectilinear-chunks enable snippet in arrays.md, and theasync.concurrency/threading.max_workersexamples in performance.md). All are now visible.Other errors:
endpoint_url(which would double the bucket name in request paths) and pointedFsspecStoreat the filesystem root; now a correct copyable pattern.order: 'F'because an earlier snippet in the same build session mutated the config; alsocodecs.bytes.name→codecs.bytes.ArrayConfigfields documented;memory://URLs were attributed toMemoryStore(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.Group.moveanddimension_separatorremoved 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.zarr[cli]extra is now documented (a plain install crashes withModuleNotFoundError); the dry-run example output corrected to the realfile://form; the "equivalent functions" now namemigrate_v2_to_v3/remove_metadata.typing_extensionsminimum corrected to 4.14; all five optional-dependency groups documented (the old text claimed universal_pathlib "must be installed separately" — it's theoptionalextra).zarr.Config.enable_gpu(nonexistent) →zarr.config.enable_gpu(); installation guidance added.site/, notdocs/_build/html; serve URL corrected; outdated doctest note removed.result="html"on a Python-repr block →result="code".Usability improvements
zarr[remote]note for the cloud example, and a "Next steps" section.group/create_group/open_group, and documents member enumeration (keys,members,in) and deletion.update_attributesfor bulk updates (each single assignment is a separate metadata write), deletion, and links consolidated metadata.use_consolidated=True/False/Noneknob, including the escape hatch for the staleness caveat.Verification
tests/test_docs.py: 57 passed, 2 skipped (GPU/cupy and a known skip).mkdocs build --strict: clean.🤖 Generated with Claude Code