readthedocs.org: the code behind Read the Docs, and what it takes to run it

What readthedocs.org is for, and who actually needs the code

Read the Docs hosts documentation for the open source community. The README describes the service as pulling Git repositories, building them automatically and hosting the result, and it names the philosophy behind that: Docs as Code, or the README's own phrase, Continuous Documentation. The documentation tools it supports include Sphinx with reStructuredText and MkDocs with Markdown, among others.

The repository you are looking at is not a library you import. It is the source code that powers readthedocs.org, a Django web application with a build pipeline attached. The README's audience list is broad: open source projects hosting public documentation, teams maintaining internal or private documentation, developers using Sphinx or MkDocs, and projects that treat documentation as part of a continuous integration workflow.

That list mixes two very different readers. Most of those people want the hosted service at app.readthedocs.org, where the quickstart is six clicks and no server. A much smaller group needs this repository: people who want to run the platform themselves, or who are extending it. If you fall into the first group, cloning this repository is the wrong move, and the README itself sends you to the hosted signup rather than to an install guide.

How the build pipeline is put together

The repository layout tells you most of the architecture. readthedocs/ is the Django project, manage.py drives it, and requirements.txt is a thin pointer to requirements/pip.txt, which is the real dependency list. Configuration lives in setup.cfg, with setup.py reduced to a single setuptools call and a comment saying the configuration is elsewhere.

Around that core sit the pieces you would expect from a service that builds code on behalf of users: dockerfiles/ and docker-compose.override.yml for containerised runs, tasks.py for task definitions, scripts/ for operational entry points, and a .circleci/ directory for CI. The build itself is the interesting part. A push to a connected repository triggers a build, the platform checks out that revision, installs the project's documentation dependencies, runs the configured documentation tool, and publishes the output under a versioned URL. The README states the outcome plainly: documentation that automatically rebuilds and updates whenever you push changes to GitHub.

Versioning is a first-class concept rather than an afterthought, which is why the README can promise that builds follow the repository. The trade-off is that the platform owns the build environment. Your documentation toolchain has to be expressible in the configuration the platform understands, and anything that needs unusual system packages or network access at build time becomes a configuration problem rather than a shell script you control.

Setting up a project on Read the Docs

The README does not contain installation instructions for the application. It points to the Read the Docs documentation for setting up and managing a project, and to the Contribution page for development setup. Docker Compose is the route the repository layout suggests, since docker-compose.override.yml and dockerfiles/ are both present at the top level, but the README gives no commands for it.

What the README does give is the quickstart for GitHub hosted projects, and it is entirely in the browser. Create an account by signing up with GitHub. When GitHub prompts you, grant access to your repositories. Log in and click Add project. Start typing the name of your repository, select it from the list, and click Continue. Review and update any project information if needed, then click Next. The README's closing line is the whole payoff: commit away, and your documentation will auto-update on every push.

For the self-hosted path the README is silent, so the entry points are simply the ones the repository files expose. Two of them are visible at the top level: manage.py, the Django management entry point, and requirements.txt, which the repository file reduces to a reference to requirements/pip.txt. No command, flag or port for running the application appears in the README, and none should be assumed from it. Treat the repository as a Django codebase to deploy, and get the deployment steps from the Read the Docs documentation and the Contribution page, which are the two places the README names.

Where self-hosting readthedocs.org gets expensive

The strongest limitation is not in the code, it is in the shape of the project. This is a multi-service Django application with a background build system, container definitions and a CI configuration. Running it means running a web tier, a database, a queue, and workers that execute untrusted build steps on behalf of whoever connects a repository. The README never claims otherwise, and it never offers a single-command install.

A second limitation is documentation coverage of operations. The README covers purpose, audience, contribution and the GitHub quickstart. It does not describe backup, rollback, upgrade order between releases or how to recover a failed build environment. Those topics are delegated to docs.readthedocs.com, which is a separate site from this repository. If you are evaluating the repository alone, you cannot confirm the operational story from it.

The third is fit. If your documentation is a directory of Markdown files that changes twice a year, this platform is heavier than the problem. The value here comes from repetition: many versions, many contributors, builds that must track commits. Without that repetition, a static site generator plus any file host does the same job with far less to operate.

How it differs from MkDocs and Sphinx used on their own

The obvious alternative is to run the documentation tool directly. Sphinx and MkDocs both build a site from source, and both are named in this README as supported inputs. The difference is where the work happens. With Sphinx or MkDocs alone, you own the invocation, the hosting, the versioning scheme and the rebuild trigger, usually by wiring the build into CI yourself and publishing the output somewhere.

Read the Docs inverts that. The tool becomes a plugin to the platform. You declare which tool and which configuration the project uses, connect a repository, and the platform handles checkout, build, versioning and hosting. The cost of that inversion is exactly what the previous section described: you adopt the platform's build environment and its operational surface along with the convenience.

A second, subtler difference is that the hosted service and this repository are not the same product. The README links to app.readthedocs.org for the service and to docs.readthedocs.com for its documentation. This repository is the engine. Choosing between them is a hosting decision, not a documentation-tool decision.

Maintenance cadence, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-21. Releases are frequent and dated: 2026.09.15, 2026.09.01 and 2026.08.26 appear in the release list, which suggests a rolling release scheme rather than occasional tagged milestones. For an operator, that cadence is a real cost. Frequent releases mean frequent upgrade decisions, and the README does not describe a supported upgrade path between them, so the migration notes you need will have to come from the CHANGELOG.rst file or the separate documentation site.

The licence is MIT, stated in the README and in the LICENSE file at the repository root. MIT is permissive: it allows use, modification and redistribution with the copyright notice preserved. Two boundaries are worth stating. The licence covers the code in this repository, which the README attributes to Read the Docs, Inc. and contributors. It does not grant you anything regarding the readthedocs.org service, its branding or its hosted infrastructure, and it says nothing about the licences of the documentation projects you build with it. That is a factual boundary, not legal advice; if your organisation has licence review, run the MIT text past it rather than this article.

The questions people ask before connecting a repository

The search questions that surface around this project are mostly about the service rather than the code, which is itself informative: most people meet Read the Docs as a hosted product and never see this repository. The answers below stick to what the README and the repository files state.

On cost, the README does not describe pricing or plan limits at all. It describes the purpose of the project and the GitHub quickstart, and links to app.readthedocs.org for signup. Anyone evaluating cost has to go to the service, not to this source tree.

On setup, the README gives a six-step GitHub quickstart and nothing for self-hosting. The distinction matters: following the quickstart gets you a project that rebuilds on every push, while running this repository is a Django deployment you assemble yourself.

On whether it is open source, the answer is yes and the licence is named: MIT, in the README and in LICENSE. The repository is public and the README invites contributions through the Contribution page.

Editorial conclusion

Adopt readthedocs.org if you need documentation builds tied to Git history, versioned URLs and a hosted or self-hosted place to serve them, and you are willing to run a Django application with Postgres, Redis and a build worker pool. Do not adopt it if your docs are a handful of static pages, or if you need a single-binary server that a junior can operate: the stack here is large and the README points you at the hosted service first. Before committing, verify the docker-compose setup in your own environment, confirm which documentation tools your project actually uses (Sphinx, MkDocs or another), and read the MIT licence text in LICENSE alongside the contribution page, since the licence covers the code in this repository and not the readthedocs.org service itself.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. readthedocs/readthedocs.org on GitHub
5. Releases