Skip to content

Documentation

This repository is the central documentation site for CADDForge.

Installed documentation

caddforge-docs ships a built static site and registers the optional caddforge docs CLI command. It depends on core's generic command extension interface, introduced in core 0.21.0. Serving the installed site uses Python's standard library; ProperDocs and its plugins are needed only for builds or authoring.

Run python -m build to create wheel and source distributions. The wheel hook runs a strict ProperDocs build into the ignored src/caddforge_docs/site/ directory. The source distribution includes the site sources, configuration, and build hook, and excludes generated site files. Editable installations also build the installed view; reinstall to refresh it after edits. Use properdocs serve --open when live reloading is needed. Build failures abort packaging.

Source of truth

For now, plugin-specific README.md files remain unchanged. Central docs should still be updated when user-facing behavior, config fields, outputs, or pipeline contracts change.

Later, plugin READMEs can be shortened to package summaries that link here.

Writing guidelines

  • Document user workflows before internal implementation details.
  • Prefer runnable CLI and Python examples.
  • Keep config examples short and valid.
  • Mention external software dependencies clearly.
  • Document canonical output paths and result keys used by pipelines.
  • Keep pipeline examples explicit about artifact names and stage IDs.
  • When plugin behavior, config fields, outputs, or pipeline contracts change, update the plugin page's documented version callout and the plugin version matrix in the same change.

Local validation

python -m pip install -r requirements.txt
properdocs build --strict

Public documentation maintenance

Use explicit public package and symbol allowlists. Do not generate the site by importing or discovering every installed plugin. scripts/update_reference.py reads only selected core files using Python's AST; the generated reference is checked in so an isolated docs build needs no scientific packages or adjacent checkout.

python scripts/update_reference.py ../caddforge-core/src/caddforge
python scripts/update_reference.py ../caddforge-core/src/caddforge --check

Generate against the reviewed core version and review signatures/docstrings for accuracy and public content. Update the generator's version description when the reference baseline changes. Scientific templates and docs/examples/manifest.json are explicit public examples, not an export of all installed tools.

python -m pip install -r requirements.txt -r requirements-test.txt
python scripts/validate_examples.py
# In a compatible public scientific environment, validate JSON schemas:
python scripts/validate_examples.py --runtime
properdocs build --strict --site-dir site
python scripts/check_links.py site
python -m pytest -q
python -m pytest tests/test_examples.py -q --require-examples

JSON schema validation checks required fields, types, enums and bounds, but deliberately cannot verify placeholder files or all custom model validators. Runtime input validation and scientific checks remain necessary. Docs-only CI checks syntax and manifest coverage; release validation adds public schemas and actual lightweight tutorial execution.

Keep tutorials complete, with input provenance and expected outputs. Label prepared-input and heavyweight examples as templates. Keep configuration downloads synchronized with page snippets, and link shared explanations for units, reproducibility, and limitations. The writing structure follows Diátaxis.

Review scientific data provenance, screenshots, datasets, and repository history before public disclosure. Never copy previous run outputs into public examples.

The documentation theme is pinned to the asset version covered by the third-party notices. Review generated dependencies and update the pins, asset hook, notices, and licence texts together when upgrading it.