Update Docs

Review the current branch or working-tree changes and ensure all documentation is up to date.

Step 1 — Identify what changed

Determine the scope of changes (from the diff, staged files, or PR):

• Which Python public APIs were added or modified?
• Which areas of the C++ or Python codebase were touched?
• Were any new features, behaviours, or options introduced?

Step 2 — User-facing documentation (docs/mkdocs/docs/)

ArcticDB user docs are built with MkDocs. The source tree:

Docstrings (NumPy format)

When authoring code, add or update complete docstrings on any public method you change, regardless of which file it's in.

When reviewing (PR review or /review skill), only require complete docstrings for public methods in the primary API files:

• python/arcticdb/version_store/library.py
• python/arcticdb/arctic.py
• python/arcticdb/version_store/_store.py

A complete docstring has all applicable sections:

• Parameters — every parameter, with type and description
• Returns — return type and what it contains
• Raises — exceptions the caller should expect
• Examples — at least one runnable example

"Accurate" is not enough — missing sections are a gap.

Tutorials

Features with multiple use cases or non-obvious behaviour need a tutorial in docs/mkdocs/docs/tutorials/. A docstring alone is insufficient for complex features.

mkdocs.yml nav

Any new documentation page must be added to the nav section of docs/mkdocs/mkdocs.yml. Without a nav entry the page is unreachable from the site.

Edge cases and disambiguation

• Behaviour that may surprise users (performance cliffs, unsupported dtypes, ordering guarantees) must be documented.
• When multiple similar features coexist (e.g., update vs append), explain "when to use A vs B".

Checklist

• Public API has complete NumPy-format docstrings (Parameters, Returns, Raises, Examples)
• Complex or multi-use features have a tutorial in docs/mkdocs/docs/tutorials/
• docs/mkdocs/mkdocs.yml nav updated for any new pages
• Edge cases, limitations, and "when to use A vs B" guidance documented where applicable

Step 3 — Claude-maintained technical docs (docs/claude/)

These docs are owned and maintained by Claude. The area→document mapping table is in CLAUDE.md under "Claude-Maintained Technical Docs".

• Read the relevant doc when starting work in an area (e.g., read CACHING.md before modifying version map cache).
• Update on change: If the code change touches an area covered by a docs/claude/ document, update that document to reflect the changes.
• Scope: Only update documents for areas actually changed. Do not touch unrelated docs.
• Keep docs high-level and terse: reference file_path:ClassName:method_name instead of copying code; use tables and bullet points over code blocks; avoid duplicating what's already in source code.

Checklist

• docs/claude/ technical doc updated for each area of code that was changed

Step 4 — Build and verify (if user-facing docs changed)

cd docs/mkdocs && mkdocs serve

Check that new pages render correctly and links resolve.