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 1/26/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 1/26/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 1/28/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 7/9/13

Binary Trading is just a new software where both novices and qualified traders
are given the opportunity to earn larger rates on the investment portfolio.

http://www.irma-hesz.de 2 weeks, 1 day ago

Properly to answer the last query first, Jimmy Young is really
a tutor of Forex, teaching others how to make good cash (and possibly a living) via Forex.

http://en.gravatar.com/forextra2015 2 weeks, 1 day ago

Good business practices require that we take ourselves seriously as entrepreneurs.
Despite the fact that I never ever worked with him personally, I know that he already helped many people in beginning up a successful home-based-business.
Since the living room is used for such a wide variety of purposes,
organizational systems often fall apart.

corporate event planners san francisco 2 weeks ago

Rob Minkoff, director of Oscar-winning animation The Lion King,
mentioned Chinese tradition was fascinating to overseas audiences.

best chinese war movies 1 week, 6 days ago

Zhang studied movie production at New York College in the 1990s and made
a few brief films as a student.

best chinese kung fu movies 1 week, 6 days ago

Right here is the right web site for anybody who wants to find out about this topic.

You realize so much its almost hard to argue with you (not that I actually would want to…HaHa).
You certainly put a brand new spin on a topic which
has been discussed for ages. Excellent stuff, just great!

baidu 1 week, 5 days ago

I think what you posted was actually very logical.
But, what about this? what if you typed a catchier title?
I am not saying your information is not solid., however what if you added a title that
makes people desire more? I mean Posts | Mark Story is a little boring.

You should peek at Yahoo’s front page and note how they create post headlines to get viewers to click.

You might add a related video or a related pic or two to
get people excited about what you’ve got to say. In my opinion, it could bring
your posts a little livelier.

ultra trim 350 supplement 1 week, 3 days ago

ilmaiset bonukset suomalainen netticasino <a href=http://kasino247.org/>pelaa nyt</a> ilmaista pelirahaa 2014 ilmaista pelirahaa casinolle

ClaudiaWhox 1 week, 2 days ago

suomalaiset kasinot ilmaista pelirahaa kasinolle <a href=http://kasino247.org/>online kasinot</a> parhaat netticasino bonukset ilmaista rahaa kasinolle

AllisonMal 1 week, 2 days ago

Person can visualize the advantages of unlimited provide of
free gold and silver hack.

gamerbounty review 1 week, 2 days ago

I got this web site from my friend who told me concerning this website and
at the moment this time I am browsing this web page and reading
very informative articles or reviews at this time.

Earn at Home Club System 2 days, 20 hours ago

Have your say: