mitk-python-docs

Read the Docs build harness for the MITK Python API documentation.

The documentation source is not stored here. It lives in the MITK repository under Wrapping/Python/docs and is the same Sphinx site built locally by the mitk_python_docs CMake target. On every Read the Docs build this repository fetches that source and builds it against the mitk-python wheel from PyPI, so the published site stays a single source of truth with the bindings.

What this repository contains

.
├── .readthedocs.yaml  # RTD build config: fetches docs from MITK, then builds
├── requirements.txt   # the mitk-python wheel to document
├── .gitignore
├── LICENSE
└── README.md

docs/ is created at build time (a sparse checkout of MITK) and is git-ignored.

How the build works

1. post_checkout sparse-clones Wrapping/Python/docs from MITK into docs/. The MITK ref is ${MITK_DOCS_REF:-develop}; override it with the MITK_DOCS_REF environment variable in the Read the Docs project settings.
2. The toolchain is installed from the fetched docs/requirements.txt and the mitk-python wheel from this repository's requirements.txt.
3. Read the Docs runs Sphinx against docs/conf.py. Autodoc imports the installed mitk package to render the API reference.

Build locally

Reproduce a Read the Docs build (Linux, macOS, or WSL; the mitk-python wheel must exist for your platform and Python version, see PyPI):

# 1. Fetch the documentation source from MITK
git clone --depth 1 --no-tags --filter=blob:none --sparse \
    --branch "${MITK_DOCS_REF:-develop}" \
    https://github.com/MITK/MITK.git .mitk-src
git -C .mitk-src sparse-checkout set Wrapping/Python/docs
cp -r .mitk-src/Wrapping/Python/docs docs
rm -rf .mitk-src

# 2. Install the toolchain and the package being documented
pip install -r docs/requirements.txt -r requirements.txt

# 3. Build
python -m sphinx -b html docs docs/_build/html

Open docs/_build/html/index.html to view the result.

Versioning

latest tracks the development line: MITK develop built against the newest mitk-python wheel on PyPI, pinned in requirements.txt. That is usually a dev wheel, but right after a release — before the next dev wheel is published — it is the release wheel itself, because a dev wheel sorts before its final release (2026.6.dev2 < 2026.6) and keeping the stale dev pin would leave latest behind the release. Bump the pin whenever a newer wheel appears.

A release gets its own version (e.g. 2026.06, served at /en/2026.06/ and linked from the matching MITK release) built from a git tag of the same name. On that tag, requirements.txt pins the released wheel and .readthedocs.yaml defaults the MITK docs ref to the matching vYYYY.MM tag, so the version stays fixed regardless of what main does. The MITK_DOCS_REF environment variable is deliberately not used for this, since it is project-wide and would redirect latest too. Read the Docs auto-detects the tag as an inactive version; activate it in the project's Versions tab to build it.

Contributing

The documentation content (Getting started, User guide, API reference) is maintained in MITK under Wrapping/Python/docs; open documentation changes there, not in this repository. Changes here should concern only the Read the Docs build itself. For the mitk-python package, see the MITK project.

License

BSD 3-Clause License, see LICENSE.