add readthedocs - #11
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a Read the Docs configuration to enable hosted Sphinx documentation builds for this repository.
Changes:
- Introduces
.readthedocs.yamlto configure RTD build environment (OS + Python). - Configures RTD to build Sphinx docs using
docs/conf.py.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # Set the OS, Python version, and other tools you might need | ||
| build: | ||
| os: ubuntu-24.04 | ||
| tools: | ||
| python: "3.13" | ||
|
|
||
| # Build documentation in the "docs/" directory with Sphinx | ||
| sphinx: | ||
| configuration: docs/conf.py | ||
|
|
There was a problem hiding this comment.
Read the Docs will not install any dependencies with the current config, so the Sphinx build is likely to fail (missing sphinx/extensions and runtime deps like anyio). Add a python: install: section to install the project with the docs extra (or otherwise install the docs requirements) so RTD can build reliably.
| build: | ||
| os: ubuntu-24.04 | ||
| tools: | ||
| python: "3.13" | ||
|
|
There was a problem hiding this comment.
The RTD build is pinned to Python 3.13, but the repo’s docs workflow sets up Python 3.12. If any dependency/extensions behave differently across versions, this can lead to “works in CI, fails on RTD” drift. Consider aligning RTD’s Python version with CI (or explicitly testing docs builds on 3.13 in CI).
| # install: | ||
| # - requirements: pyproject.toml | ||
|
|
There was a problem hiding this comment.
The commented example - requirements: pyproject.toml is misleading: RTD’s requirements: expects a requirements file (e.g., requirements.txt), not a pyproject.toml. Either update this comment to show the correct python: install: approach for a pyproject-based project (e.g., pip install with extras) or remove it to avoid future copy/paste issues.
| # install: | |
| # - requirements: pyproject.toml | |
| # install: | |
| # - method: pip | |
| # path: . | |
| # extra_requirements: | |
| # - docs |
This pull request introduces a new Read the Docs configuration file to the project. This will enable automated documentation builds using Sphinx with a specified environment.
Documentation build setup:
.readthedocs.yamlconfiguration file to set up Read the Docs, specifying Ubuntu 24.04 as the OS, Python 3.13 as the interpreter, and pointing Sphinx to use thedocs/conf.pyconfiguration.