Read the Docs — Documentation Hosting for Open Source Projects

Introduction

Read the Docs is a documentation hosting platform that builds docs from your version control repository on every commit. It supports Sphinx and MkDocs, handles versioning by branch or tag, and serves the result with full-text search and PDF generation.

What Read the Docs Does

• Automatically builds documentation on every push via webhook integration
• Hosts multiple versions of docs corresponding to branches and tags
• Provides full-text search across all documentation pages
• Generates PDF, EPUB, and zipped HTML downloads from the same source
• Supports custom domains with automatic HTTPS provisioning

Architecture Overview

Read the Docs is a Django web application backed by PostgreSQL and Elasticsearch. When a webhook fires, a Celery task clones the repository, installs dependencies in an isolated environment, runs the doc build tool (Sphinx or MkDocs), and uploads the output to storage. Nginx serves the built docs with version-based URL routing. The platform can be self-hosted via Docker Compose.

Self-Hosting & Configuration

• Self-host with the open-source codebase and Docker Compose
• Configure builds via .readthedocs.yaml in your repo root
• Set Python version, OS image, and build commands in the config file
• Enable pull request builds to preview documentation changes before merging
• Configure notifications for build failures via email or webhook

Key Features

• Automatic versioning that maps git branches and tags to doc versions
• Pull request previews that build docs from PR branches for review
• Environment variable support for injecting secrets during builds
• Traffic analytics showing page views and search queries
• Ad-supported free hosting for open-source projects

Comparison with Similar Tools

• GitHub Pages — static hosting only, no automatic versioning or search
• Netlify — general static site hosting, requires custom versioning setup
• GitBook — visual editor and hosted platform, limited self-hosting
• Docusaurus — a doc site generator, not a hosting platform; needs separate deployment

FAQ

Q: Is Read the Docs free for open-source projects? A: Yes. Open-source projects hosted on public repositories get free documentation hosting with community ads.

Q: Can I use it with MkDocs? A: Yes. Set the mkdocs key in .readthedocs.yaml and point it to your mkdocs.yml configuration.

Q: How does versioning work? A: Each branch or tag becomes a separate version. Readers can switch versions via a dropdown on the documentation site.

Q: Can I self-host Read the Docs? A: Yes. The platform is open source under the MIT license and includes Docker-based deployment instructions.

Sources

• https://github.com/readthedocs/readthedocs.org
• https://docs.readthedocs.io/