Choosing the Right Default Version for Your Read the Docs Project
Learn how to pick the default version in Read the Docs so visitors see the right docs for stable releases while developers can still access the latest build.
Loading…
ReadMeFeed / Community knowledge
#sphinx
Real questions. Useful conversations. Find the people who know your stack.
readthedocsDiagnosing ReadTheDocs Build Failures from .readthedocs.yaml Misconfiguration
ReadTheDocs build failing with YAML errors, ModuleNotFoundError, or missing artifacts? A diagnostic table, ordered checks, and a pinned reference config to isolate the cause fast.
Pin Read the Docs builds and versions to stop docs drift
Pin the build environment in readthedocs.yml and map repository tags to Read the Docs versions to keep documentation reproducible and aligned with releases.
Setting Up and Verifying a Custom Domain on ReadTheDocs
Learn how to add a custom domain to your ReadTheDocs project, configure DNS, update Sphinx, and verify the SSL certificate. Follow this step‑by‑step guide to ensure your docs load securely on your own domain.
Automating Sphinx Documentation Deployments with Read the Docs
Learn how to automate your Sphinx documentation pipeline using Read the Docs, including .readthedocs.yaml configuration, dependency management, and versioning strategies.
Sphinx version mismatch between local and Read the Docs builds causes inconsistent output
Goal Produce identical HTML output when building a Sphinx project locally and on Read the Docs, despite the platform pinning a specific Sphinx version in its build image. Constraints and uncertainty Read the Docs builds run in a controlled Docker image that includes a fixed Sphinx release (for example, 7.2.x in the current "ubuntu-22.04" image). Local enviro
ImportError: No module named 'mypackage' during ReadTheDocs autodoc build
ImportError in RTD Build Environment The ReadTheDocs build logs report ImportError: No module named 'mypackage' when the Sphinx autodoc extension attempts to import the target module. Local builds succeed because the package is installed globally or the source directory is present on the local sys.path . Environment Constraints ReadTheDocs utilizes a clean v
pythonRead the Docs build failure and live version persistence limits
Documentation Versioning and Build Failures Read the Docs employs a build-server architecture that triggers documentation generation via VCS webhooks. When a build is initiated, the system attempts to transform source files into static HTML using tools like Sphinx. A critical behavior occurs when a new build fails: the platform typically maintains the previo
readthedocs.yaml config version 2 vs. RTD build fleet: default image and interpreter resolution when build.os and build.tools.python are omitted
Integration boundary A repository's readthedocs.yaml (config version 2) and Read the Docs' build fleet form the primary integration boundary for documentation builds. The build.os and build.tools.python keys explicitly select the container image (Ubuntu release) and Python interpreter, but both are optional. Unresolved behavior When these keys are omitted, R