Yes, really.
Ok so you have started with Django, the Python web-framework and are finding yourself wasting a lot of precious little seconds on their regularly updated documentation online?
(The docs folder in your downloaded django tarball is just not so up to date!)
Well then this is the guide for you. It will explain in neat little steps on how to go about obtaining the freshest of all django documentation online (From their code repository) and build it for use on your local machine or web-server.
First off, here are the requirements you will need installed before you begin:
- SVN (Subversion)
- Sphinx (Python)
- make, etc… build tools
For example, on a Debian/Ubuntu system you would run:
harsh@work:~$ sudo apt-get install subversion python-sphinx make
Fetch the documentation
Once you have got them all installed, lets start the process by fetching the documentation files from Django’s SVN repository:
harsh@work:~$ mkdir django && cd django harsh@work:~/django$ svn co http://code.djangoproject.com/svn/django/trunk/docs
After the above command finishes downloading the documentation files (It’s checking-out source code from the repository), you should have a folder named docs under the current working folder (~/django in my example’s case).
Build the HTML documentation
Our next task is to build these reStructuredText (reST) files into HTML using Sphinx. We issue the following command to do so:
harsh@work:~/django$ cd docs harsh@work:~/django/docs$ make html
Very simple! All the built files would go to the ~/django/docs/_build folder if you’re following my example. This folder would contain two folders named doctree and html. The html one is our sweet nectar of immortality!
Note: There are other make [options] that you could probably use, such as pickle, latex, etc. Also, the file conf.py under the documentation root might be of interest to people who would like to customize things a little more.
Done!
Now that we have our files ready, we can move it to a preferred place. For me it was /var/www (My local web-server root). So all I then had to do was:
harsh@home-desktop:~/django/docs$ mv _build/html /var/www/django-doc
That’s it. Now you can just browse to this folder either directly (Files) or by putting it on your local development server. Enjoy!
P.s. With some more configuration, you can automate this process and even make it update weekly or so for you. So add all the salt you would like for taste, and happy hacking!
