Building the documentation

The documentation follows TreeIG’s Sphinx, MyST Markdown, and PyData Sphinx Theme conventions. NumPy-style API docstrings use Napoleon; mathematical notation uses MathJax. Navigation keeps the complete compact guide visible.

From the repository root, using Python 3.11 or newer:

python -m pip install -e ".[docs]"
python -m sphinx -W --keep-going -b html docs docs/_build/html
python scripts/check_docs_discovery.py

Open docs/_build/html/index.html in a browser. Documentation dependencies are optional and do not change CBaseline’s runtime requirements. The documentation configuration reads the version from pyproject.toml using Python 3.11’s tomllib. Generated HTML is ignored by Git.

Examples

To run the README and integration examples, also install:

python -m pip install treeig scikit-learn shap

The examples use generated data and fixed seeds. They need no external dataset. Classification snippets explain how to adapt a fitted model; they require its actual logits, class order, and chosen reference population.

Continuous integration and publishing

The Documentation workflow builds HTML with warnings treated as errors and uploads a downloadable artifact on pushes and pull requests. Like TreeIG, it deploys to GitHub Pages on pushes to main or manual runs on main. Pull requests build without deploying.

For initial publication, select Settings → Pages → GitHub Actions as the repository’s Pages source, then run the workflow on main. The expected site address is https://ludgerhentschel.github.io/cbaseline/ after a successful deployment. Adding these files alone does not publish the site.

Edit topic pages under docs/, keeping the README focused on the package, papers, and the first examples. Keep docs/requirements.txt and the docs extra in pyproject.toml synchronized.

Discovery files

Maintain the repository-root llms.txt as an annotated map to the published guides. Sphinx copies this single source to the documentation base URL through html_extra_path. Use rendered API links because raw Sphinx sources contain autodoc instructions rather than expanded signatures and docstrings.

sphinx-sitemap generates sitemap.xml with the project prefix from html_baseurl, which also supplies canonical page URLs. Important pages define concise descriptions in their myst.html_meta YAML front matter.

The discovery check runs after the HTML build in CI. It verifies the copied index, local link targets, sitemap URLs, canonical links, descriptions, and expanded API and example content. After deployment, check the public /cbaseline/llms.txt and /cbaseline/sitemap.xml endpoints and external links.