CI and Publishing

Documentation validation is separate from deployment and Python package upload.

Validate a change

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

The tests build wheels and rebuild from a source distribution, check packaged assets, and test the installed-docs CLI and server. Tutorial integration tests require compatible core and data-science installations; they report skips when those packages are absent. Run them explicitly in a compatible public-component environment before release.

python -m pytest tests/test_examples.py -q --require-examples

GitHub branch and tag pushes and pull requests run documentation checks without requiring deployment. Publication jobs depend on successful validation. Optional scientific template schema checks use an explicit list of public configuration classes; they do not discover arbitrary installed plugins.

Host the generated site

GitHub Pages uses .github/workflows/pages.yml. Enable Pages with the GitHub Actions source, then opt in with repository variable DOCS_PUBLISH_ENABLED=true. Builds produce static artifacts on ordinary changes, but deployments run only for an enabled default branch, including a manual workflow on that branch. Release tags run validation without deploying Pages.

Configure the public site and repository URLs in properdocs.yml after hosting is established. The source is platform-neutral. The installed docs package ships its own site; hosting is not required to use caddforge docs.

Python distribution releases

caddforge-core owns Python modules and the CLI. The metadata-only bundle publishes the caddforge distribution and pins the reviewed component set. See release prerequisites before any release.

Every public component uses .github/workflows/release.yml for branch/PR validation and publication on pushed v* tags, matching PyOCL and the maintained third-party tools. A single Python 3.12 build produces the wheel and source archive; tests install that exact wheel on Linux with Python 3.10 and 3.12. Publication depends on all required checks. Manual runs and branch pushes do not publish. No PYPI_PUBLISH_ENABLED variable is used.

Metadata checks run on ordinary builds as well as tags. They reject private dependencies and direct Git requirements, compare wheel/source metadata, and require a release tag to match the built version. Release tags must have public versions without local or .dev suffixes; a 0.x version still represents the project's initial development series. Core and plugin versions come from Git tags. Docs and bundle versions are explicit in pyproject.toml and must be updated before tagging.

The tests run from temporary fixture copies without checkout src directories. Core, data-science, GUI, ML, QM and docking run their regression suites. Descriptors run plugin, clustering and PheSA tests without downloading ANI weights. MD runs configuration, trajectory and workflow contract tests; external engines and long simulations remain separate. FEP tests orchestration and settings without requiring an OpenFE runtime. FEP and docking install the candidate wheel with its [gui] extra so GUI regression tests exercise the declared dependencies, including the published caddforge-gui package. Each selection is recorded in scripts/ci_tests.json. These profiles do not claim GPU or complete scientific-engine validation.

Docs additionally validates source examples, assets, links and distribution rebuilding, tests the installed viewer, and requires successful execution of the CLI/Python tutorials using published core and data science. The docs wheel is installed with its [test] extra, including Rich for terminal-output assertions. The bundle runs the ownership migration with an explicit core source checkout, and requires a clean full installation from public PyPI before publishing. Its release must follow its pinned components.

For each PyPI project, configure a Trusted Publisher with GitHub owner idorsia, the corresponding repository, workflow filename release.yml, and environment pypi. For the bundle the PyPI project is caddforge, while the repository is caddforge-bundle. GitHub environments may require reviewer approval if desired. Repository workflows cannot configure these PyPI account settings for you. Publish core first, then GUI before FEP and docking. Publish docking and descriptors before MD, and data-science before docs. Publish the bundle last.

Pushing a release tag is the publication action once the Trusted Publisher is configured. .github/workflows/pages.yml handles site deployment independently and retains the explicit DOCS_PUBLISH_ENABLED=true opt-in.