- Debian VM provisioned with python 2.7.x
- All python dependencies and setup tools are installed:
.. prompt:: bash $ 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
- Git:
.. prompt:: bash $ sudo apt-get install git
- Git repo is
git.corp.company.com:git/docs/documentation.git
- Source documents are in
../docs/source
- Sphinx:
.. prompt:: bash $ sudo pip install sphinx
Note
Not using sudo may prevent access. “error: could not create '/usr/local/lib/python2.7/dist-packages/markupsafe': Permission denied”
To host your documentation on a local RTD installation, set it up in your VM:
.. prompt:: bash $ mkdir checkouts cd checkouts git clone https://github.com/rtfd/readthedocs.org.git cd readthedocs.org sudo pip install -r requirements.txt
Error: error: command 'gcc' failed with exit status 1
Resolution: Run the following commands:
.. prompt:: bash $ 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:
.. prompt:: bash $ 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
.. prompt:: bash $ sudo pip install -r requirements.txt
Run the following commands:
.. prompt:: bash $ ./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: monami.b@email.com Password: pa$$word
Navigate to the ../checkouts/readthedocs.org
folder in your VM and run the following command:
.. prompt:: bash $ ./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.
Example:
git.corp.company.com:/git/docs/documentation.git
. - Clone the documentation sources from Git in the VM.
- Navigate to the root path for documentation.
- Run the following Sphinx commands:
.. prompt:: bash $ make html
This generates the HTML documentation site using the default Sphinx theme. Verify the output in your local documentation folder under ../build/html
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.
Workaround-1
In your machine, navigate to the
.ssh
folder:.. prompt:: bash $ cd .ssh/ cat id_rsa
Copy the entire Private Key.
Now, SSH to the VM.
Open the
id_rsa
file in the VM:
.. prompt:: bash $ vim /home/<username>/.ssh/id_rsa
- Paste the RSA key copied from your machine and save file (
Esc
.:wq!
).
Workaround 2
SSH to the VM using the -A
directive:
.. prompt:: bash $ ssh document-vm -A
This provides all permissions for that particular remote session, which are revoked when you logout.
Log into http://[VM IP ADDRESS]:[PORT]
using the django superuser creds and follow these steps.
Select :guilabel:`<username>` > :guilabel:`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.
Click Next.
- Select :guilabel:`<username>` > :guilabel:`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).