How to read PDF of Django Documentation on iPod

This is how I got a pdf of the latest Django Documentation onto my iPod. Of course this would work on your iPhone (iPad?) too. Everything shown here is don in Ubuntu. But the steps shouldn't be much different on other OS, be it Windows or Mac OS X, as long as you have root.

Step 1: get the source.
Good news, Django is Open Source! OK, that's kinda silly. But it's the fundamental reason all this is possible. Anyway, more useful info is that Django uses svn as its version control system and the Doc is part of the source in the repository. So let's check the source out:

svn co http://code.djangoproject.com/svn/django/trunk/

Caution: this is a fairly big repo so the check-out takes quite a bit of time!

Step 2: Compile the documentation
Here's the key to the next piece: Django uses a Python documentation generator called Sphinx to produce the Doc. Sphinx compiles reStructuredText into multiple formats, including HTML, CHM and LaTeX. And the source of the documentation is maintained in reStructuredText format. Our final goal here is to get a pdf, obviously we would generate that from LaTex. So, we need the sphinx-build script to compile the source into LaTeX. For Ubuntu users, the sphinx package in the official repo is called python-sphinx, install it:

sudo apt-get install python-sphinx

This will automatically install several related packages. When it's done, the compile should be smooth:

sphinx-build .../path/to/Doc/source/ .../path/to/the/latex/files

Step 3: Get the PDF
Now it's time to turn the LaTeX source code from last step into a PDF file. I'm a daily LaTeX user on Ubuntu, so for others there might be some additional latex-related packages to install from the official repo. But when I tried running pdflatex command, it complains that two style package were missing. I had to find them online: wrapfig.sty, titlesec.sty. According to Ubuntu Community Documentation, I did the following:

mkdir ~/texmf/tex/latex/titlesec
mv titlesec.sty ~/texmf/tex/latex/titlesec/
mkdir ~/texmf/tex/latex/wrapfig
mv wrapfig.sty ~/texmf/tex/latex/wrapfig/
texhash ~/texmf/

Basically, this creates folders for each package under the home path and informs tex of the added packages.

And now it should compile:

cd .../path/to/latex/files
pdflatex django.tex django.toc

When its done, you should find django.pdf lying in the folder, epic.

Step 4: Put the PDF into the iPod/iPhone(/iPad?)

There are tons of PDF reading apps in App Store. The one I've been using is a free app called Good Reader. It lets you read text, pics and PDF. The reason I'm using it is that it supports some really handy ways to transfer the files on to the mobile devices, including Dropbox.

If you haven't used Dropbox to sync files between your different devices I highly recommend that you follow this link to create a account and start using it immediately. For a starter, it's waaaay more convenient than emailing files as attachments. Anyway, once you get Dropbox folder syncing on your box, drop in djang.pdf there.

Open Good Read on your iPod/iPhone, go to Web Downloads -> Connect to Server -> Create New Connection to -> Dropbox. Fill in your username and password, hit "add". Go back to Connect to Server, click the the newly added account to navigate to the Dropbox folder, find django.pdf and download it.

And we are done, enjoy your mobile, beautiful copy of Django Documentation!