Saturday, March 22

Generate PDF with Sphinx Documentation System


One of the most important things in any project is documentation, yet it is usually the last thing if it is done at all.

I've recently change jobs and in the new company we create SDKs for different platform and languages. We are lean and fast and do a lot of changes quickly but we realize we better get our documentation abilities agile as well as our development skills.

What is Sphinx?

After evaluating several documentation tools I've found Sphinx. This is the tool used for Python documentation. The reason it looks best for me is that it is a mature project, it has a notion of version which is important for documentation as it is important for the software itself. It has many extensions that are not required for me now but I'm sure will come in handy later.

Output to HTML

The first and most important requirement is that the tool will be able to output HTML based documentation. This is because we plan to have each specific platform's SDK created in it native tool and use HTML as the one unified languages to connect them all together (thank you hyperlink).
If you follow the quick-start application of sphinx all you need to do to create HTML docs is 

make html

Output to PDF

This is not a must but it will be nice to be able to create PDF documentation both for download and in-browser reading. The problem is that when I run make latexpdf I got this error:

make[1]: pdflatex: No such file or directory

After google it for a bit I was able to find a post about how to generate PDF  using Sphinx. From there I was able to find the line after pdflatex command as follows:
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
Using this I was able to find MacTeX-2013 Distribution which is Mac package for TeX tools. The problem is that the main download is 2.2GB download but a few clicks away is Smaller packages for only the essential tools.