readthedocs/readthedocs.org

★ 8,351PythonAudience · developerComplexity · 4/5LicenseSetup · hard

Mindmap

mindmap
  root((Read the Docs))
    What it does
      Doc hosting
      Auto build and publish
    How it works
      Git webhooks
      Sphinx support
      MkDocs support
    Hosted service
      GitHub sign-in
      One-click add project
    Audience
      Open source maintainers
      Contributors

mindmap root((Read the Docs)) What it does Doc hosting Auto build and publish How it works Git webhooks Sphinx support MkDocs support Hosted service GitHub sign-in One-click add project Audience Open source maintainers Contributors

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Self-host the entire Read the Docs platform for your organization to publish internal documentation automatically on every git push.

USE CASE 2

Contribute a bug fix or feature to the readthedocs.org service by running the full application locally.

USE CASE 3

Study how a large Django application integrates with Sphinx and MkDocs to automate documentation builds from Git webhooks.

USE CASE 4

Add your open-source project to the hosted readthedocs.org service: sign in with GitHub, grant access, and get auto-publishing in minutes.

Tech stack

PythonDjangoSphinxMkDocs

Getting it running

Difficulty · hard Time to first run · 1day+

This is the full Read the Docs platform application, not a library, self-hosting requires a complete Django + database + build worker infrastructure setup.

Use freely for any purpose, including commercial, as long as you keep the copyright notice.

In plain English

This is the source code for Read the Docs, the free documentation hosting service that many open-source software projects use to publish their documentation online. If you have ever clicked a link to docs.something.io or readthedocs.io while looking up how to use a Python library or other open-source tool, you have likely used a site hosted by Read the Docs. The service works by connecting to a Git repository, watching it for changes, and automatically building and publishing the documentation every time someone pushes new code. You point it at your repository, and it handles the build and hosting steps. It supports the two most common documentation systems in the Python world: Sphinx, which uses a format called reStructuredText, and MkDocs, which uses standard Markdown. The quickstart described in the README is short: create an account by signing in with GitHub, grant access, add your project by searching for the repository name, and you are done. After that, every commit you push triggers an automatic documentation rebuild without any further manual steps. The README describes this approach as continuous documentation, treating docs the same way continuous integration treats code. This repository is not a library you install and use in your own project. It is the actual application that runs the readthedocs.org platform. Developers who want to contribute to the platform itself or run a self-hosted version would work with this code. The project is licensed under MIT.

Copy-paste prompts

Prompt 1

Walk me through setting up a local development environment for the readthedocs.org codebase on macOS so I can submit a bug fix pull request.

Prompt 2

Explain the Read the Docs build pipeline from a git push to the docs appearing live, which modules handle the webhook, the build queue, and the static file serving?

Prompt 3

Show me how readthedocs.org handles Sphinx vs MkDocs projects differently, which parts of the codebase diverge for each?

Prompt 4

I want to add a new feature to Read the Docs that shows a word count on each doc page, where in the codebase would I start?

Open on GitHub → Explain another repo

← readthedocs on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.