Before proceeding to setup your own local Read the Docs instance, it may be worth familiarizing yourself with the Read the Docs development setup and standards, which details the local development setup with Docker, and the installation guide.
Again, if your primary reasons for considering a private installation are to connect to private repositories or to have fine grained access control over your documentation, please consider Read the Docs for Business. It has those features and many more and helps support Read the Docs!
Assumptions and Prerequisites¶
- Debian VM provisioned with python 2.7.x
- All python dependencies and setup tools are installed:
sudo apt-get install python-setuptools sudo apt-get install build-essential sudo apt-get install python-dev sudo apt-get install libevent-dev sudo easy_install pip
sudo apt-get install git
- Git repo is
- Source documents are in
sudo pip install sphinx
Not using sudo may prevent access. “error: could not create ‘/usr/local/lib/python2.7/dist-packages/markupsafe’: Permission denied”
Local RTD Setup¶
To host your documentation on a local RTD installation, set it up in your VM:
mkdir checkouts cd checkouts git clone https://github.com/readthedocs/readthedocs.org.git cd readthedocs.org sudo pip install -r requirements.txt
Possible errors with a local RTD setup¶
error: command 'gcc' failed with exit status 1
Resolution: Run the following commands:
sudo apt-get update sudo apt-get install python2.7-dev tk8.5 tcl8.5 tk8.5-dev tcl8.5-dev libxml2-devel libxslt-devel sudo apt-get build-dep python-imaging --fix-missing
On Debian 8 (jessie) the command is slightly different:
sudo apt-get update sudo apt-get install python2.7-dev tk8.5 tcl8.5 tk8.5-dev tcl8.5-dev libxml2-dev libxslt-dev sudo apt-get build-dep python-imaging --fix-missing
Also don’t forget to re-run the dependency installation
sudo pip install -r requirements.txt
Configure the RTD Server and Superuser¶
Run the following commands:
./manage.py migrate ./manage.py createsuperuser
This will prompt you to create a superuser account for Django. Enter appropriate details. For example:
Username: monami.b Email address: [email protected] Password: pa$$word
RTD Server Administration¶
Navigate to the
../checkouts/readthedocs.org folder in your VM and run the following command:
./manage.py runserver [VM IP ADDRESS]:8000 curl -i http://[VM IP ADDRESS]:8000
You should now be able to log into the admin interface from any PC in your LAN at
http://[VM IP ADDRESS]:8000/admin using the superuser account created in django.
Go to the dashboard at
http://[VM IP ADDRESS]:8000/dashboard and follow these steps:
- Point the repository to your corporate Git project where the documentation source is checked in.
- Clone the documentation sources from Git in the VM.
- Navigate to the root path for documentation.
- Run the following Sphinx commands:
This generates the HTML documentation site using the default Sphinx theme. Verify the output in your local documentation folder under
Possible errors administering a RTD server¶
Error: Couldn’t access Git Corp from VM.
Resolution: The primary access may be set from your base PC/laptop. You will need to configure your RSA keys in the VM.
In your machine, navigate to the
cd .ssh/ cat id_rsa
Copy the entire Private Key.
Now, SSH to the VM.
id_rsafile in the VM:
Paste the RSA key copied from your machine and save file (
SSH to the VM using the
ssh document-vm -A
This provides all permissions for that particular remote session, which are revoked when you logout.
Build Documentation on Local RTD Instance¶
http://[VM IP ADDRESS]:[PORT] using the django superuser creds and follow these steps.
For a new project¶
Select <username> > Add Project from the user menu.
Click Manually Import Project.
Provide the following information in the Project Details page:
- Name: Appropriate name for the documentation project. For example – API Docs Project
- Repository URL: URL to the documentation project. For example - git.corp.company.com:/git/docs/documentation.git
- Repository Type: Git
Select the Edit advanced project options checkbox.
For an existing project¶
- Select <username> > Projects from the user menu.
- Select the relevant project from the Projects list.
- Select latest from the Build a version dropdown.
- Click Build. This will take you to the Builds tab where the progress status is displayed. This may take some time.
- If the installation doesn’t work on VM using your login/LDAP credentials, try running the operations as root (su).