# Read the Docs — Documentation Hosting for Open Source

> A free documentation hosting platform that builds and publishes Sphinx and MkDocs projects automatically from version control.

## Install

Save in your project root:

# Read the Docs — Documentation Hosting for Open Source

## Quick Use
```bash
pip install sphinx
sphinx-quickstart docs
# Add a .readthedocs.yaml to your repo root:
# version: 2
# build:
#   os: ubuntu-22.04
#   tools:
#     python: "3.11"
# sphinx:
#   configuration: docs/conf.py
# Then connect your repo at readthedocs.org
```

## Introduction
Read the Docs is a documentation hosting platform that automatically builds and publishes documentation from your version control repository. It supports Sphinx (reStructuredText) and MkDocs (Markdown), provides versioned documentation tied to branches and tags, and serves millions of documentation pages for open-source projects at no cost.

## What Read the Docs Does
- Automatically builds documentation on every commit or pull request
- Hosts versioned docs tied to Git branches and tags
- Provides full-text search across documentation pages
- Supports custom domains with free SSL certificates
- Generates PDF, ePub, and HTML downloads from the same source

## Architecture Overview
Read the Docs watches your repository for changes via webhooks. On each push, it spins up a build environment that installs your project dependencies and runs Sphinx or MkDocs to produce HTML output. Built documentation is served from a CDN with version-aware URL routing (e.g., /en/latest/, /en/v2.0/). The platform is itself open source and can be self-hosted, though most projects use the managed service.

## Self-Hosting & Configuration
- Create a `.readthedocs.yaml` in your repository root for build configuration
- Specify Python version, OS, and build commands in the config file
- Connect your GitHub, GitLab, or Bitbucket repository through the web dashboard
- Configure custom domains via DNS CNAME records
- Self-host using the readthedocs.org codebase with Docker for private documentation

## Key Features
- Versioned documentation from Git branches and tags with a version switcher
- Pull request previews for reviewing documentation changes before merge
- Built-in full-text search powered by Elasticsearch
- Traffic analytics to see which pages get the most visits
- Supports Sphinx extensions, MkDocs plugins, and custom themes

## Comparison with Similar Tools
- **GitHub Pages** — Static hosting only, no built-in versioning or search
- **Netlify** — General static hosting, no documentation-specific features
- **GitBook** — Commercial documentation platform, SaaS model
- **Docusaurus** — React-based static generator, self-hosted deployment
- **Mintlify** — Modern documentation hosting, commercial with free tier

## FAQ
**Q: Is Read the Docs free?**
A: Yes, for open-source projects. A paid plan (Read the Docs for Business) is available for private repositories and additional features.

**Q: Can I use Markdown instead of reStructuredText?**
A: Yes. Use MkDocs as your documentation tool, or use MyST-Parser with Sphinx to write Markdown that compiles through Sphinx.

**Q: How does versioning work?**
A: Each branch or tag in your repository can be activated as a documentation version. Readers switch between versions using a dropdown in the docs.

**Q: Can I self-host Read the Docs?**
A: Yes. The platform is open source and can be deployed on your own infrastructure using the official repository and Docker.

## Sources
- https://github.com/readthedocs/readthedocs.org
- https://docs.readthedocs.io/

---
Source: https://tokrepo.com/en/workflows/read-docs-documentation-hosting-open-source-1e5e5c90
Author: AI Open Source