Update Feb 6th 2010: PDF generation of the django docs is much easier now
I really really like Django. This simple MVC framework saved me from the pains and depression of Zope. Sure I learned a lot of cool concepts like interfaces and adaptors from the good book, but ultimately I wasn’t able to get my project off the ground in a whole month whereas with Django I was productive very fast. And that is a lot to say for someone who had almost no web-dev experience until a couple of months ago.
There docs folder of your django distribution has a lot of very useful text files with very detailed documentation that explains how to do simple things and more advanced things as well. You can grep in that folder to look for things, or sometimes grep-ing in the actual source code can also be helpful.
Of course, when learning nothing is better than having a printed book which you can read and consult while programming, writing templates and searching for solutions. The django book is cool and all but I think the docs themselves are of such high quality that they should be your primary source for learning, examples AND reference.
So here it is for you: Django 1.0 Documentation (pdf) (~700pages)
The remainder of this post is a howto about generating the docs yourself from the docs/ directory and the sphinx—latex—pdf method. I posted my “fix” over here earlier, but now I wanted to flesh out the process with more details for other people out there that insist on raping trees.
Step 1: Getting the software
If you are running on a Linux system then you should go and get the default latex distribution from your repository. I ran
sudo apt-get install python-sphinx texlive-latex-base.
You might also need texlive-latex-extra texlive-latex-recommended, but I am not sure if have these because I am a tex guy or because I had to use them for the docs.
Step 2: Changing conf.py
The Makefile has a latex target for the sphinx doc builder. The settings for are stored in the file called conf.py.
For some reason, in the latex target of conf.py only the index is built so if you run make latex you will get a 50p index with titles and a lot of white space.
Change that file to:
# Options for LaTeX output
# ------------------------
# The paper size ('letter' or 'a4').
latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]).
latex_documents = [
(master_doc, 'django.tex', 'Django Documentation', 'Django Software Foundation', 'manual'),
]
Where master_doc is defined somewhere higher up in the file as “contents” — so basically EVERYTHING in the docs directory.
Step 3: Generating the latex code
In the docs directory run:
make latex
and a couple of minutes later the _build/latex dir will be full of .tex, .pngs and .gifs
Step 4: Convert .gifs to .pngs
The pdflatex program used to generate a pdf file from latex source can work with .jpgs, and .pngs. It has some trouble working with .gifs though so we need to change a few pics. If you have imagemagick installed this is easy:
cd _build/latex
for file in *.gif ; do
echo converting `basename $file .gif` from gif to png;
convert $file `basename $file .gif`.png;
done
Then open django.tex in your favourite text editor and search for four \includegraphics statements that involve gifs. In vim I did:
/includegraphics.*gif/
and replace the gif extention with png
(If you don’t have time to do this don’t worry about it, there are just 4 gifs that aren’t so important — you probably won’t even notice that they are not there)
Step 5: Build the pdf
This takes about 30 seconds and you will see some errors while it runs. Something about pt being used as a unit of measure. Ignore those (simply press the spacebar) and the program will continue running and generate your beautiful new 700 page document.
This is my version of the 1.0 docs.
Now all you have to do is find a free printer and a quality 2” binder to hold your new Django 1.0 documentation version papier.