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.

Comments

Hi Mark,

Since I am one of the most important contributors to the French cookbook translation effort, I understand very well why Sphinx, but I have some questions: – using Git/Github will be mandatory to contribute? – installing Sphinx and Python on my PC too?

Thanks for answer

avairet on 26/1/11

avairet: You would only need sphinx an python if you wanted to generate the html/other output yourself. The documentation source would just be plain text files that don’t require anything special to read/write. There has been some discussion around having a web interface that allows online editing. But initially I think it will be all git, at least until the online editing tool is created.

mark story on 26/1/11

For information, Github allows inline editing and commits.

When browsing a file source you have write access to (in your fork for instance), there is an “Edit” link which could make it easier to translate or fix a typo without using any Git commands.

It is still very simple (impossible to edit multiple files etc…) but efficient.

Pierre Martin on 28/1/11

Does your site have a contact page? I’m having trouble locating it but, I’d like to shoot you an email.
I’ve got some ideas for your blog you might be interested in hearing. Either way, great site and I look forward to seeing it expand over time.

www.youtube.com on 9/7/13

Have your say:

*
* You can use Textile markup, but be reasonable