CADDForge Documentation

Central documentation site for the CADDForge toolbox.

These sources describe the reviewed public snapshots in the version matrix. Documentation release 0.3.0 is identified by source tag v0.3.0; package-index publication remains pending. Release tags identify source revisions; package-index publication is separate. See the release notes for the packaged changes.

View installed documentation

The planned public bundle includes caddforge-docs automatically; its pins and release remain pending. For core-only or selective installations, install the documentation package into the same environment once its new public release is available. Until then, use the source installation under Local preview:

python -m pip install caddforge-docs
caddforge docs

caddforge docs is available only when caddforge-docs is installed. The package installs caddforge-core>=0.21.0 automatically; core 0.21.0 includes CLI extension discovery. The built site ships with the docs package, so viewing it requires no checkout, documentation build tools, or network connection. Its content matches the installed docs release.

The command opens the default browser and keeps serving until you press Ctrl+C. By default it binds to 127.0.0.1 on an automatically assigned port. Override the listening address or port as needed:

caddforge docs --host 0.0.0.0 --port 8001
caddforge docs --host localhost --no-browser
caddforge docs --host ::1

Hostnames, IPv4, and IPv6 addresses are supported. With wildcard bindings (0.0.0.0 or ::), the automatic browser opens the matching loopback URL. The terminal prints the listening address and browser URL; remote clients can use the server's reachable hostname or address and the printed port. --no-browser keeps the server running without launching a browser. If automatic opening fails, use the printed URL manually.

Local preview

python -m pip install -r requirements.txt
properdocs serve

Then open http://127.0.0.1:8000.

Alternatively, install the optional docs dependencies from pyproject.toml:

python -m pip install ".[docs]"

For an editable install, python -m pip install -e ".[docs]" also builds the packaged site. Reinstall after editing sources to refresh caddforge docs, or use properdocs serve --open for live authoring. The packaged site is generated under src/caddforge_docs/site/ and ignored by Git. For source installations, install a compatible core revision first: python -m pip install -e ../caddforge-core. See the documented version matrix.

Build

properdocs build --strict

The generated static site is written to site/.

To build distributable documentation packages:

python -m pip install build
python -m build

Wheel builds run ProperDocs in strict mode and include all rendered pages and assets. The source distribution includes the Markdown, configuration, and build hook needed to rebuild the wheel. Build dependencies are installed in the isolated build environment and are not runtime requirements.

To run tests, install the authoring and test extras, then run python -m pytest -q:

python -m pip install -e ".[docs,test]"
python -m pytest -q

Publishing

This repository has separate package and site workflows:

• .github/workflows/release.yml builds and tests the installed wheel on Python 3.10 and 3.12, then publishes to PyPI only for pushed v* tags.
• .github/workflows/pages.yml validates and optionally deploys GitHub Pages.

Update the explicit version in pyproject.toml before creating a matching annotated release tag. Configure a PyPI Trusted Publisher for this repository, release.yml, and the pypi environment. Release core and data-science first; the installed-wheel tests execute the documented tutorials with those public packages.

The MkDocs source is platform-neutral.

Public documentation and validation

Start with docs/getting-started/first-workflow.md and first-pipeline.md for runnable examples with invented input data. The example library supplies configurations for 26 public scientific workflows. Heavyweight templates require prepared inputs and external engines; they are not bundled experimental datasets.

python -m pip install -r requirements.txt -r requirements-test.txt
python scripts/validate_examples.py
properdocs build --strict
python scripts/check_links.py site
python -m pytest -q

Install compatible public core/data-science packages before requiring tutorial tests with python -m pytest tests/test_examples.py -q --require-examples. Public API reference generation uses an explicit AST allowlist; builds do not discover installed scientific plugins. Wheel builds render the site in strict mode and check local links in rendered pages.

See contributing, security reporting, and the release checklist. The project uses MIT; bundled third-party assets retain the licences listed in the third-party notices. Public-index availability remains a release prerequisite. Pages deployment requires DOCS_PUBLISH_ENABLED=true and is separate from package publication. Branch pushes, pull requests, and manual runs never publish packages; pushing a matching v* release tag publishes the tested wheel and source archive through the configured PyPI Trusted Publisher.