Installation

Here is a step by step guide on how to install Read the Docs. It will get you to a point of having a local running instance.

Requirements

First, obtain Python 3.6 and virtualenv if you do not already have them. Using a virtual environment is strongly recommended, since it will help you to avoid clutter in your system-wide libraries.

Warning

Currently Read the Docs is using Django 1.11.x and this version of Django has a bug which breaks database migrations if you are using sqlite 3.26.0 or Newer. So, we recommend using sqlite < 3.26.0 to run Read the Docs properly on your machine.

Additionally Read the Docs depends on:

  • Git (version >=2.17.0)

  • Mercurial (only if you need to work with mercurial repositories)

  • Pip (version >1.5)

  • Redis

  • Elasticsearch (only if you want full support for searching inside the site)

    • Follow Search documentation for more instruction.

Note

If you plan to import Python 2 projects to your RTD, then you’ll need to install Python 2 with virtualenv in your system as well.

In order to get all the dependencies successfully installed, you need these libraries.

If you are having trouble on OS X Mavericks (or possibly other versions of OS X) with building lxml, you probably might need to use Homebrew to brew install libxml2, and invoke the install with:

CFLAGS=-I/usr/local/opt/libxml2/include/libxml2 \
LDFLAGS=-L/usr/local/opt/libxml2/lib \
pip install -r requirements.txt

Install:

sudo apt-get install build-essential
sudo apt-get install python-dev python-pip python-setuptools
sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev

If you don’t have redis installed yet, you can do it with:

sudo apt-get install redis-server

Install:

sudo yum install python-devel python-pip libxml2-devel libxslt-devel
On other operating systems no further dependencies are required, or you need to find the proper equivalent libraries.

Get and run Read the Docs

Clone the repository somewhere on your disk and enter to the repository:

git clone --recurse-submodules https://github.com/rtfd/readthedocs.org.git
cd readthedocs.org

Create a virtual environment and activate it:

virtualenv --python=python3 venv
source venv/bin/activate

Next, install the dependencies using pip (make sure you are inside of the virtual environment):

pip install -r requirements.txt

This may take a while, so go grab a beverage. When it’s done, build the database:

python manage.py migrate

Then create a superuser account for Django:

python manage.py createsuperuser

Now let’s properly generate the static assets:

python manage.py collectstatic

Now you can optionally load a couple users and test projects:

python manage.py loaddata test_data

Note

If you do not opt to install test data, you’ll need to create an account for API use and set SLUMBER_USERNAME and SLUMBER_PASSWORD in order for everything to work properly. This can be done by using createsuperuser, then attempting a manual login to create an EmailAddress entry for the user, then you can use shell_plus to update the object with primary=True, verified=True.

Finally, you’re ready to start the web server:

python manage.py runserver

Visit http://127.0.0.1:8000/ in your browser to see how it looks; you can use the admin interface via http://127.0.0.1:8000/admin (logging in with the superuser account you just created).

For builds to properly work as expected, it is necessary that the port you’re serving on (i.e. python manage.py runserver 0.0.0.0:8080) matches the port defined in PRODUCTION_DOMAIN. You can use readthedocs/settings/local_settings.py to modify this (by default, it’s localhost:8000).

While the web server is running, you can build the documentation for the latest version of any project using the update_repos command. For example to update the pip repo:

python manage.py update_repos pip

Note

If you have problems building a project successfully, it is probably because of some missing libraries for pdf and epub generation. You can uncheck this on the advanced settings of your project.

What’s available

After registering with the site (or creating yourself a superuser account), you will be able to log in and view the dashboard.

Importing your docs

One of the goals of readthedocs.org is to make it easy for any open source developer to get high quality hosted docs with great visibility! Simply provide us with the clone URL to your repo, we’ll pull your code, extract your docs, and build them!

We make available a post-commit webhook that can be configured to update the docs whenever you commit to your repo. See our Importing Your Documentation page to learn more.

Further steps

By now you can trigger builds on your local environment, to encapsulate the build process inside a Docker container, see Build Environments.

For building this documentation, see Building and Contributing to Documentation.

And for setting up for the front end development, see Front End Development.