Generating Documentation with Sphinx

In the release announcement for 1.3.7, it was tentatively announced that CakePHP would be moving its documentation over to ReST, Git and sphinx. Having documentation in a git repo, and using sphinx to generate documentation has a few nice wins, that would be difficult to achieve with the current book application.

• Offline docs. A frequent request is to make some sort of offline version of the docs available. A git repo makes the source files available offline. Sphinx, has the option to generate CHM files, e-books, and PDF’s giving even more offline documentation options.
• Easier to support multiple versions. Currently when new versions of CakePHP come out, updating all the links in the documentation is a huge chore. Because of the way sphinx works, this problem goes away, which is nice. Sphinx also makes it possible to have urls that contain the documentation version, which makes should make it easier to switch between versions of the documentation.
• Less code to maintain. Currently the CakePHP team maintains the cookbook application. Using sphinx to generate documentation, means that people who are pros at documentation can make our lives easier. Allowing us to focus on what we do best.

Why sphinx

I looked at a number of tools before coming to sphinx as possibly the best tool for the job. Other tools I looked at were:

• Gollum: Gollum powers the wiki pages at github.com. Its provides git integration, as well as online editing. However, we would need to heavily modify it to add in table of contents, pdf/chm/ebook output, authentication and translation support.
• Docbook: Is another great tool for generating documentation and is used all over the world. It can be used to output all kinds of formats similar to sphinx. The big problem I had with docbook is the very verbose xml format, that can be hard to learn, and master.
• Custom tooling: This would take us back to where we are, which is a place we wanted to get away from.

Sphinx offers an easy to learn syntax for writing documentation, the ability to output in several formats, and through using git and github the ability to edit online, and its a tool the CakePHP team doesn’t have to maintain which is nice. In addition sphinx is used by a number of large projects like python and bazaar

Installing sphinx

As mentioned before, sphinx is a python library. It can be easily installed using easy_install or pip. I installed it with easy_install.

easy_install sphinx

You should see a bunch of dependencies installed, and a message letting you know that sphinx was installed.

Starting a new project

You can create a new sphinx project using sphinx-quickstart. A command line script will guide you through creating your first sphinx project. You create documentation in any text editor using ReST syntax which is very similar to markdown and is quite easy to learn. After editing your files, you can create the html output using make. Generally its as easy as using make html. This will generate the HTML version of the docs which can be plopped into any web-server and viewed.

I hope in the next few months to make some progress on the git + sphinx documentation as well as create some custom templates that fit with the CakePHP sites.