Open-source project
readthedocs/readthedocs.org avatar
readthedocs/readthedocs.org

Read the Docs: the Python source behind a documentation hosting service

The source code that powers readthedocs.org

8,412 stars3,717 forksPythonMIT

At a glance

What is it?
This repository is the platform code that powers readthedocs.org, not the place to sign up. It automates building, versioning, and hosting for Sphinx and MkDocs projects, and it tells you far more about how the service is built and tested than about how to run it yourself.
Who is it for?
Use the hosted service if your goal is publishing documentation for a project, and follow the six step GitHub quickstart, because this repository is the platform source rather than the thing you are signing up for. Use the repository directly when you plan to contribute a fix, or when you have decided to run your own instance and can accept owning the stack that dockerfiles/ and manage.py imply.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 3 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • readthedocs/readthedocs.org8,412 ★ · +23
Star history
Repository2026-09-222026-11-15
readthedocs/readthedocs.org8.4k8.4k

23 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

This repository is the platform source, not the signup page

The repository description is one line and it settles a lot of confusion: The source code that powers readthedocs.org. What lives here is the Python application behind the service, not the hosted documentation itself and not the account flow. Teams looking for a place to publish Sphinx or MkDocs output go to app.readthedocs.org, and the README points the signup step at Read the Docs through an underscored link. The service takes Git repositories, builds the documentation automatically, and hosts it, and it supports many documentation tools rather than a fixed one, naming Sphinx with reStructuredText and MkDocs with markdown among the examples. Its stated audience is open source projects hosting public documentation, teams maintaining internal or private documentation, and projects already running continuous integration for their docs. The framing the README puts on all this is documentation as code, the same care and workflow as source code. That is a product promise, and it is worth keeping separate from what this tree can tell you, which is how the machinery is built and tested.

The GitHub quickstart is six clicks and commits no file

The fastest path described is entirely a browser exercise. Create an account by signing up with GitHub, grant access to your repositories when GitHub prompts, log in and click "Add project", start typing the repository name, select it from the list and click "Continue", then review the project information and click "Next". After that, pushes update the documentation automatically. Nothing in that sequence writes a file into your repository, which is the first thing worth noticing. A team that wants its documentation build reproducible across machines and contributors has to go past the quickstart and maintain configuration itself, and this repository carries a .readthedocs.yml at its root for exactly that purpose, even though the quickstart never mentions the file. So there are two paths, and they do not meet. The click path gets you a live site today. The committed file is what you need once a second person or a second machine is involved, and nobody walks you from one to the other here.

requirements.txt defers the whole dependency list to a subdirectory

Installing this repository is not one step, and the top level file says so instead of hiding it. The entire contents of requirements.txt are a reference to requirements/pip.txt plus a comment giving the reason, so that a plain `pip install -r requirements.txt` works the way people expect. The effect is that you cannot read the dependency set from the top of the tree. You have to open requirements/pip.txt, and the repository ships a requirements/ directory for the rest of the pins. Nothing here is a published package name you would add to your own project's dependencies, which matters if you arrived looking for a client library or a plugin. What gets installed is a web application with manage.py at the root, not a reusable component, and its packaging is kept deliberately thin.

python
-r requirements/pip.txt
# just referencing for a natural `pip install -r requirements.txt`

setup.py is a three line shim and the metadata hides in setup.cfg

Open setup.py and you find the entire packaging story: an import, a comment saying the configuration is in setup.cfg, and a call to setup() with no arguments. Whatever packaging metadata the project declares lives in that setup.cfg instead. The split follows a setuptools convention rather than being a mistake, but it costs anyone auditing the project something real. You cannot get a summary of what gets installed without opening a second file, and the one file named setup.py tells you nothing on its own. The same pattern repeats across the root directory. Pytest configuration sits in pytest.ini, coverage in .coveragerc, test environments in tox.ini and tox.embedapi.ini, and lint rules in .ruff.toml. The root is a map of where to look rather than a place where answers are.

python
from setuptools import setup


# Configuration is in setup.cfg
setup()

Version settings live at docs.readthedocs.com, not in this tree

Versioning is named as one of the three things the platform automates, next to building and hosting, and it is the one a self hosted operator gets the least help with here. There is a .env at the root, but the README does not document which variables belong in it. The entries do include dockerfiles/, docker-compose.override.yml and manage.py, so a local stack is reachable, and the README routes you to docs.readthedocs.com for setup and management rather than repeating any of it. The configuration file a reader expects, .readthedocs.yml, sits at the root. Releases carry calendar dates rather than semantic versions: 2026.10.13post2, 2026.10.21 and 2026.10.27 all shipped inside one month, and the last push landed on 2026-11-02. The cadence is active, and a date string is a poor thing to pin, and a CHANGELOG.rst exists at the root while the settings reference does not.

Nine tools gate a commit, plus a separate suite for the embedded API

Anyone planning to contribute is signing up for a toolchain, and the root directory is the invoice. Continuous integration runs through CircleCI in .circleci/, coverage is tracked by codecov through .codecov.yml and .coveragerc, formatting and linting are pinned in .ruff.toml, hooks come from .pre-commit-config.yaml, and .git-blame-ignore-revs marks rewritten commits so that formatting churn does not follow a file around in blame. Prose is not exempt. .vale.ini configures Vale as a style checker, and the .tx/ directory points at a translation workflow. Tests split in two as well: tox.ini holds the general matrix and tox.embedapi.ini names a distinct suite for the embedded API rather than folding it into the main run. A .claude/ directory and an AGENTS.md at the root carry instructions for coding agents. None of this is unusual for a hosted service, but the setup cost lands on whoever opens the first pull request.

MIT covers the code, and a self hosted instance is the engine without the corpus

The license is MIT, and the README dates its copyright line to 2025, crediting Read the Docs, Inc. and contributors, which is what lets a team fork the platform and run it on its own infrastructure. What you get from running it is the build and hosting machinery: Git integration, versioned builds, Sphinx and MkDocs support, the serving side. What you do not get is the part that makes the hosted service worth using, namely the documentation already written and indexed there and the community around it. A self hosted instance is a documentation server you now have to run, back up, upgrade onto a date string, and secure. If your need is public docs for one project, signing up on the hosted service and following the six step quickstart takes minutes, and this repository is only the code behind it. Read it when you want to contribute a fix or understand the architecture, not when you are deciding how to publish.

Editorial conclusion

Use the hosted service if your goal is publishing documentation for a project, and follow the six step GitHub quickstart, because this repository is the platform source rather than the thing you are signing up for. Use the repository directly when you plan to contribute a fix, or when you have decided to run your own instance and can accept owning the stack that dockerfiles/ and manage.py imply. Verify two things before you commit either way: that the .readthedocs.yml you write matches the configuration version documented at docs.readthedocs.com, and that the release tag you pin, one of the 2026.10 date tags, speaks the same settings schema your file assumes.

Frequently asked questions

How do I set up Read the Docs?

For a GitHub hosted project the README describes a browser quickstart: sign up with GitHub, grant repository access, click "Add project", type the repository name and click "Continue", review the information and click "Next", and documentation then rebuilds on every push. For self hosted setup the repository routes you to https://docs.readthedocs.com/.

Is Read the Docs open source?

Yes. The repository is written in Python, its description is The source code that powers readthedocs.org, and the README states the license as MIT with a copyright line dated 2025 crediting Read the Docs, Inc. and contributors. Releases are tagged with calendar dates such as 2026.10.27 rather than semantic versions.

Can I self host Read the Docs from this repository?

The MIT license permits running your own instance, and the tree carries dockerfiles/, docker-compose.override.yml, manage.py and a .env file that point toward a local stack. The repository does not give a single install command for standing up the platform and instead sends you to https://docs.readthedocs.com/ for setup and management instructions.

Where are the .readthedocs.yml settings documented?

The file is listed at the root of this repository next to manage.py, setup.cfg, tox.ini and docs/. What keys it accepts and what they mean is documented at https://docs.readthedocs.com/, which the README names as the complete documentation for setting up and managing a project.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. readthedocs/readthedocs.org on GitHub
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/readthedocs-readthedocs-org.svg)](https://hysenlabs.com/projects/readthedocs-readthedocs-org)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/readthedocs-readthedocs-org.svg)](https://hysenlabs.com/projects/readthedocs-readthedocs-org)

Was this useful?