Version-aware documentation on ReadTheDocs without breaking search
Control which documentation version users see and search on ReadTheDocs using version-aware configuration and Sphinx conditionals.
Loading…
ReadMeFeed / Community knowledge
#sphinx
Real questions. Useful conversations. Find the people who know your stack.
readthedocsDiagnosing Build Failures in Read the Docs: Sphinx and Environment Issues
A diagnostic guide to resolving Read the Docs build failures caused by missing dependencies, Python version mismatches, and Sphinx configuration errors.
pythonConfigure Read the Docs Builds with .readthedocs.yml: Python Version, Dependencies, and Custom Commands
Learn how to control Read the Docs builds by committing a .readthedocs.yml file that pins Python version, installs dependencies, and overrides the default Sphinx command.
ReadTheDocs v2 Configuration: Pinning Builds, Adding Formats, and Migrating from Legacy YAML
Learn how to migrate to ReadTheDocs v2 config, pin build images and Python versions, add PDF/EPUB output, use conda for system dependencies, and avoid common pitfalls like legacy file conflicts and missing directory changes.
Choosing the Right Build Trigger for ReadTheDocs: Webhooks vs. Manual Builds
Choose the right build trigger for ReadTheDocs: webhook‑based automatic builds or manual/CI‑triggered builds. A practical guide with example config, trade‑offs, and a step‑by‑step Sphinx setup.
Pin your Read the Docs build environment with .readthedocs.yaml
Use .readthedocs.yaml to pin Python, dependencies, and the Sphinx builder so Read the Docs builds match your local output.
Managing Multiple Docs Versions in ReadTheDocs: Flyout Menu & Version Control Explained
Learn how to configure ReadTheDocs to host stable, latest, and release‑tagged documentation with a flyout menu. A practical guide that covers configuration files, alias mapping, and trade‑offs.
One Repo, Many Docs: How Read the Docs Turns Git Tags Into Versioned Documentation
Read the Docs builds one documentation site per Git branch or tag, giving you stable/latest/release URLs for free. Here's how the versioning model works, with a worked tag-push example and the trade-offs to plan for.
Stop Reviewing Docs by Diff: Use Read the Docs Pull Request Previews
Reviewing docs by diff hides rendering problems. Read the Docs pull request preview builds render a temporary site for each PR and post a status check, letting reviewers see layout and links before merge.