Building and contributing to documentation

As one might expect, the documentation for Read the Docs is built using Sphinx and hosted on Read the Docs. The docs are kept in the docs/ directory at the top of the source tree, and are divided into developer and user-facing documentation.

Contributing through the Github UI

If you’re making small changes to the documentation, you can verify those changes through the documentation generated when you open a PR and can be accessed using the Github UI.

  1. click the checkmark next to your commit and it will expand to have multiple options

  2. click the “details” link next to the “docs/readthedocs.org:docs” item

    _images/details_link.png
  3. navigate to the section of the documentation you worked on to verify your changes

Contributing from your local machine

If you’re making large changes to the documentation, you may want to verify those changes locally before pushing upstream.

  1. clone the readthedocs.org repository:

    $ git clone --recurse-submodules https://github.com/readthedocs/readthedocs.org/
    
  2. create a virtual environment with Python 3.8 (preferably the latest release, 3.8.12 at the time of writing), activate it, and upgrade pip:

    $ cd readthedocs.org
    $ python3.8 -m venv .venv
    $ source .venv/bin/activate
    (.venv) $ python -m pip install -U pip
    
  3. install documentation requirements

    (.venv) $ pip install -r requirements/testing.txt
    (.venv) $ pip install -r requirements/docs.txt
    
  4. build the documents

    To build the user-facing documentation:

    (.venv) $ cd docs
    (.venv) $ make livehtml
    

    To build the developer documentation:

    (.venv) $ cd docs
    (.venv) $ RTD_DOCSET=dev make livehtml
    
  5. the documents will be available at http://127.0.0.1:4444/ and will rebuild each time you edit and save a file.