Installation

Installing RTD is pretty simple. Here is a step by step plan on how to do it.

First, obtain Python and virtualenv if you do not already have them. Using a virtual environment will make the installation easier, and will help to avoid clutter in your system-wide libraries. You will also need Git in order to clone the repository.

Once you have these, create a virtual environment somewhere on your disk, then activate it:

virtualenv rtd
cd rtd
source bin/activate

You will need to verify that your pip version is higher than 1.5 you can do this as such:

pip --version

If this is not the case please update your pip version before continuing:

pip install --upgrade pip

Create a folder in here, and clone the repository:

mkdir checkouts
cd checkouts
git clone https://github.com/rtfd/readthedocs.org.git

Next, install the dependencies using pip (included with virtualenv):

cd readthedocs.org
pip install -r pip_requirements.txt

Note

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 pip_requirements.txt

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

cd readthedocs
./manage.py syncdb

This will prompt you to create a superuser account for Django. Do that. Then:

./manage.py migrate

Go ahead and load in a couple users and a test projects:

./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.

Finally, you’re ready to start the webserver:

./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).

While the webserver is running, you can build documentation for the latest version of a project called ‘pip’ with the update_repos command. You can replace ‘pip’ with the name of any added project:

./manage.py update_repos pip

Solr (Search) Setup

Apache Solr is used to index and search documents. This is an optional requirement, and only necessary if you want to develop or use search.

Additional python requirements necessary to use Solr:

pip install pysolr
pip install pyquery

Fetch and unpack Solr:

curl -O http://archive.apache.org/dist/lucene/solr/3.5.0/apache-solr-3.5.0.tgz
tar xvzf apache-solr-3.5.0.tgz && SOLR_PATH=`pwd`/apache-solr-3.5.0/example

Generate the schema.xml file:

./manage.py build_solr_schema > $SOLR_PATH/solr/conf/schema.xml

Start the server:

cd $SOLR_PATH && java -jar start.jar

Index the data:

./manage.py build_files # creates database objects referencing project files
./manage.py update_index

Note

For production environments, you’ll want to run Solr in a more permanent servelet container, such as Tomcat or Jetty. Ubuntu distributions include prepackaged Solr installations. Try aptitude install solr-tomcat or aptitude install solr-jetty.

See /etc/[solr|tomcat6|jetty] for configuration options. The schema.xml file must be replaced with the version built by django-haystack.

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.

From the dashboard you can import your existing docs provided that they are in a git or mercurial repo.

Creating new 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! We provide a simple editor and two sample pages whenever a new project is created. From there its up to you to fill in the gaps - we’ll build the docs, give you access to history on every revision of your files, and we plan on adding more features in the weeks and months to come.

Importing existing docs

The other side of readthedocs.org is hosting the docs you’ve already built. 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 on our site whenever you commit to your repo, effectively letting you ‘set it and forget it’.

Installation with Vagrant

It is also possible to run RTD using Vagrant, using Vagrant v1.1+ and the Salt plugin for Vagrant, by running the following commands:

vagrant plugin install vagrant-salt
vagrant up

The Vagrant virtual machine will take a while to create and provision, and will leave a virtual machine running an instance of RTD with the following settings:

URL:http://localhost:8000 Username:docs Password:docs

Note

The hostname localhost is used here, though it is possible to test RTD and subdomains by adding entries in /etc/hosts for readthedocs.org and your subdomains on readthedocs.org, pointing to 127.0.0.1 on the host system. The site will be available at http://readthedocs.org:8000 with the proper records set up.

The repository is shared with the host file system, so edits can be made outside the virtual environment.