Metadata-Version: 2.5
Name: caddforge-docs
Version: 0.3.0
Summary: Central documentation site for the CADDForge toolbox.
Author-email: Manuel Sellner <manuel.sellner@idorsia.com>, Christoph Sager <christoph.sager@idorsia.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: caddforge-core>=0.21.0
Provides-Extra: docs
Requires-Dist: mkdocs-material==9.7.7; extra == 'docs'
Requires-Dist: mkdocs-section-index>=0.3; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Requires-Dist: properdocs>=1.6; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
Provides-Extra: test
Requires-Dist: build>=1.2; extra == 'test'
Requires-Dist: hatchling>=1.26; extra == 'test'
Requires-Dist: jsonschema>=4.18; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Requires-Dist: rich>=13.8; extra == 'test'
Requires-Dist: tomli>=2; (python_version < '3.11') and extra == 'test'
Description-Content-Type: text/markdown

# CADDForge Documentation

Central documentation site for the CADDForge toolbox.

These sources describe the reviewed public snapshots in the
[version matrix](docs/plugins/version-matrix.md). 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](docs/development/release-notes.md) 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](#local-preview):

```bash
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:

```bash
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

```bash
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`:

```bash
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

```bash
properdocs build --strict
```

The generated static site is written to `site/`.

To build distributable documentation packages:

```bash
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`:

```bash
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.

```bash
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](CONTRIBUTING.md), [security reporting](SECURITY.md), and the
[release checklist](docs/development/release-readiness.md). The project uses MIT;
bundled third-party assets retain the licences listed in the
[third-party notices](docs/explanation/third-party-notices.md). 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.
