Contribute and verify documentation

The package uses uv and Python 3.11–3.14. Clone the package repository, then:

uv sync --locked
uv run pytest
uv run pyright --warnings
uv run ruff check src tests scripts examples benchmarks
uv run ruff format --check src tests scripts examples
uv run python examples/investigation.py
uv run python scripts/generate_assets.py --check
uv build

Read the package’s developer map for architecture, evidence contracts and algorithm details. The source package is MIT licensed, with bea-tools extraction attribution preserved.

Documentation site

Use the Node version in .nvmrc:

npm ci
npm run format
npm run validate
npm run develop

Validation checks formatting, code fences, site configuration, source metadata, Astro diagnostics, production output and internal links. Preserve the Clinical Slate styling and the getting-started, guides, concepts, reference and contributing navigation.

Write examples for readers

Start with a concrete question, show the shortest useful sequence of steps, and explain the result. Prefer descriptive names and explicit intermediate variables. Use small datasets whose counts readers can check by hand. A few repeated lines are often easier to follow than a helper, nested comprehension, or generalized loop.

Show output that helps the reader make a decision. Save reports and figures with ordinary file-writing calls. Keep assertions, markup checks, and tests of nonmutation in scripts/example-checks/, outside the displayed examples and downloads. Handle a missing recommendation when it matters, explaining what the reader can do next.

Introduce concepts before technical vocabulary. Keep counting units, missing-value rules, and consequential limits beside the example that needs them. Put exact formulas and search rules in Measurement details and implementation architecture in the package developer documentation.

Verify the examples

Each function page pairs a synthetic-data narrative with a downloadable script in public/examples/. Keep its Python blocks runnable in sequence. Generate the download from those blocks so readers see the same code in both places. Maintain the numerical and rendering checks separately in scripts/example-checks/; those fixtures verify the interpretation independently of the displayed formatting.

From the documentation checkout, run this with a Python environment containing the documented Fieldwork dependencies (including the optional Unicode extra for display-mode examples):

python scripts/sync-function-examples.py
python scripts/validate-function-examples.py --source-repo ../fieldwork

The validator exports the exact commit from docs-source.json into a temporary directory, without changing the package checkout. It checks function signatures and argument coverage, executes the displayed examples, checks the downloads match those examples, runs the numerical checks, and compares generated SVG/HTML files with the checked-in assets byte for byte. Displayed output must match execution except for invisible trailing whitespace. Use --page census to execute one function page during editing. CI installs the recorded package and runs the same validation.

The full run also executes Getting Started and each guide. Guides receive the dataframe and imports from Getting Started, then run independently so they cannot accidentally rely on another guide’s variables.

Downloadable scripts perform the exports shown on their pages in the current working directory. Run them in a scratch directory when regenerating assets, review the results, then copy the intended files into public/examples/. The package release asset bundle remains separately tracked in public/generated/.

Keep visuals tied to code

Every package release regenerates availability, census, grain, path and topology images by executing examples through the package renderers. Copy the release’s generated asset archive into public/generated/ alongside corresponding content changes. Review the PNGs and offline HTML before committing. Do not hand-edit generated evidence or screenshots.

This site tracks GitHub’s latest stable release. Update every field in docs-source.json, affected content, installation instructions, and generated assets in the same reviewable pull request. Validate the site and review the Cloudflare preview before merging.