This project publishes its documentation on Read the Docs (RTD):
- Public site: https://xmlsec.readthedocs.io/
- RTD config: ../.readthedocs.yaml
- Sphinx config: source/conf.py
- Docs source: source/
Read the Docs does not usually require you to upload files manually. Instead, it watches the GitHub repository and builds the docs from the latest pushed commit.
For this repository, RTD is configured to:
- use config version
2 - build on
ubuntu-24.04 - use the Python version pinned in
.python-version - build with Sphinx using
doc/source/conf.py - install
uv, then install the project and thedocsdependency group fromuv.lockwithuv sync
That means every successful RTD build uses the repository contents plus the settings in .readthedocs.yaml.
If you changed the docs, or changed code that affects autodoc output, validate locally first.
Follow CONTRIBUTING.md to install uv and choose how to get the native libraries. Autodoc imports xmlsec to render the API pages, so the package has to build.
Keep the environment variables for the option you chose, such as PYXMLSEC_STATIC_DEPS=true, set in your shell. The docs dependencies are in the docs dependency group, and uv run installs them in the next step. That group needs Python 3.12+ because of Sphinx 9.1.0; the project's default development Python already meets this.
uv run --group docs make -C doc htmlBuilt HTML will be placed in:
doc/build/html/
Open doc/build/html/index.html in a browser and check the pages you changed.
If the RTD project is already connected to GitHub, this is the normal deployment path:
- Edit the docs or code.
- Commit the changes.
- Push the branch to GitHub.
- RTD receives the webhook event.
- RTD rebuilds the matching version and publishes it.
For this repository, the current Git branch is master, and latest on RTD commonly tracks the repository default branch.
Example:
git add doc/source .readthedocs.yaml README.md
git commit -m "Update documentation"
git push origin masterIf you changed files outside those paths, add the correct files instead of using the sample git add command above.
If you already pushed your changes but the site did not update:
- Open the Read the Docs project for
xmlsec. - Go to the build/version page.
- Trigger a build for the version you want, usually
latest. - Wait for the build to finish and review the logs if it fails.
Typical reasons a manual rebuild is needed:
- GitHub integration/webhook is missing or broken
- the target branch/version is inactive on RTD
- a previous build failed and you want to rebuild after fixing the branch
If RTD has not been connected yet, an admin needs to set it up once:
- Sign in to Read the Docs with a GitHub account that has access to
xmlsec/python-xmlsec. - Import the repository.
- Confirm RTD is using the repository root
.readthedocs.yaml. - Make sure the GitHub integration/webhook is enabled.
- Make sure the
latestversion is active.
After that, pushes to GitHub should trigger builds automatically.
The Python package needs native xmlsec and libxml2 libraries. Check the environment variables and packages for your option in CONTRIBUTING.md, then retry.
Check:
- the build logs in RTD
- whether
.readthedocs.yamlis valid - whether
doc/source/conf.pystill builds cleanly - whether the target branch/version is active
Read the Docs manages versions from Git branches and tags. Verify which branch latest points to, and whether stable is mapped to a branch or tag you expect.