# Read the Docs — Documentation Hosting for Open Source Projects

> Read the Docs builds and hosts documentation from your repository automatically, supporting Sphinx, MkDocs, and versioned docs out of the box.

## Install

Save in your project root:

# Read the Docs — Documentation Hosting for Open Source Projects

## Quick Use
```yaml
# .readthedocs.yaml
version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
sphinx:
  configuration: docs/conf.py
```
Push to your repository, then import the project at readthedocs.org.

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-04fbb4ce
Author: AI Open Source