Read the Docs — Documentation Hosting Platform for Open Source

Introduction

Read the Docs is the standard hosting platform for open-source project documentation. It automatically builds documentation from Sphinx or MkDocs source files on every commit, hosts the output with versioned URLs, and provides full-text search across all pages. Thousands of open-source projects rely on it for their public documentation.

What Read the Docs Does

• Builds documentation from Sphinx, MkDocs, or Jupyter Book source on every push to the repository
• Hosts multiple versions of the documentation tied to branches and tags
• Generates PDF, ePub, and single-page HTML formats alongside the web version
• Provides full-text search powered by Elasticsearch across the entire documentation set
• Integrates pull request previews so reviewers can see documentation changes before merge

Architecture Overview

The platform watches repositories via webhooks. On each trigger, it clones the repo into a build environment, runs the configured documentation builder, and publishes the output to a CDN-backed hosting layer. A Django backend manages projects, builds, and users, while Celery handles asynchronous build tasks. Elasticsearch powers the search index.

Self-Hosting & Configuration

• Use the Docker Compose setup from the repository for local or private deployments
• Configure via .readthedocs.yaml in the project root to control build settings
• Set the Python version, extra dependencies, and build commands in the config file
• Supports custom domains with automatic HTTPS via Let's Encrypt integration
• Enable pull request builds for documentation review workflows

Key Features

• Automatic builds on every commit with webhook integration for GitHub, GitLab, and Bitbucket
• Versioned documentation tied to Git branches and tags with a flyout version selector
• Multi-format output including HTML, PDF, ePub, and zipped HTML
• Built-in full-text search across all pages and versions
• Pull request previews for reviewing documentation changes before merge

Comparison with Similar Tools

• GitHub Pages — static hosting only; Read the Docs adds automatic builds, versioning, and search
• Netlify — general static site hosting; Read the Docs is purpose-built for documentation with versioning
• GitBook — commercial documentation platform; Read the Docs is free for open source and self-hostable
• Docusaurus — React-based doc site generator; Read the Docs is a hosting platform that works with any builder

FAQ

Q: Is it free for open-source projects? A: Yes. The hosted service at readthedocs.org is free for open-source projects with community ads.

Q: Can I self-host it? A: Yes. The platform is open source under the MIT license and can be deployed using Docker Compose.

Q: Which documentation builders are supported? A: Sphinx, MkDocs, and Jupyter Book are the primary supported builders.

Q: How does versioning work? A: Each Git branch or tag can be activated as a documentation version, and users switch between them via a dropdown.

Sources

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