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
Create a folder in here, and clone the repository:
mkdir checkouts
cd checkouts
git clone http://github.com/rtfd/readthedocs.org.git
Next, install the dependencies using pip
(included with virtualenv):
cd readthedocs.org
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
If you like, you can load up some test projects:
./manage.py loaddata test_data
./manage.py update_repos
Or you can skip it and start with a fresh, empty site. 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).
Apache Solr is used to index and search documents.
Additional python requirements necessary to use Solr:
pip install pysolr
pip install pyquery
Fetch and unpack Solr:
curl -O http://apache.mirrors.tds.net/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/[solrjetty] for configuration options. The schema.xml
file must be replaced with the version built by django-haystack.
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 either create new documentation, or import your existing docs provided that they are in a git or mercurial repo.
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.
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'.
Usually, readthedocs.org generates its own conf.py
files, by extracting a few values (such as copyright
, html_theme
, source_suffix
and version
) from the project's conf.py
file. This is to avoid the possibility of arbitrary code execution within the python files. As a result, projects with special extensions, themes, or templates won't work correctly. We are planning to support popular themes in future.
For projects which need to be able to run code in conf.py, there is a white list for users that we trust to have these abilities. To get on the white list, ask on IRC (#readthedocs on Freenode (chat.freenode.net)).