I develop stuff and have opinions on things -
About me/Contact


Moving from AsciiDoc to Sphinx/reST

A bit of context

A few years back, Poezio was using codingteam as a forge, using its bugtracker, its version control system integration, and more specifically, its wiki.

We quickly moved from the integrated wiki system, because it was not practical to maintain documentation while editing a webpage with the (not nice) wiki syntax.

We moved to AsciiDoc, because it looked good, was plain text, easy to maintain in the source code tree, and the syntax was simple, while having enough features to satisfy our needs.

The (my) issues with AsciiDoc

As the project grew, so did its documentation (since we could commit the documentation updates along with the modifications, it was an easy way to keep it up-to-date).

As you can see on the Poezio 0.7.5 documentation, it is very simple, and straightforward, but it has several shortcomings that, in my opinion, make it an unperfect solution for software documentation:

  • No notion of Project

    You cannot cross-reference terms between pages, you have to create references and link to them manually (the links to the pages have also to be made using the .html targets, which is not cool)

  • You cannot use markup or special syntax in the description lists (e.g. this page)

  • The analysis of the language is quite poor, which explains, for example, while the table of contents needs javascript.

  • There is no way to search inside the project (and use google is not a good answer)

As I started to write an API document for writing plugins in poezio, it occurred to me that AsciiDoc was (really) not suited for the task, so I remembered a project, a long time ago, where I used Sphinx to document an API, and that it was enjoyable to write.

The solution: Sphinx

One of the most used language in python documentation is reST, which is logical, because it was somewhat created by python developers, for python developers (it is also, by the way, the markup language I use to write blog posts).

Along with reST, the tool used for the standard Python documentation is Sphinx, so those two work really well together. Sphinx provides goodies for documenting code, since you can just write documentation in reST (+Sphinx extensions) inside the docstrings, you can then just create a rst file that will fetch the docstrings from your code and display them nicely.

Sphinx also provides an integreated (client-side) search engine, which highlights the searched terms in the page, and filters the pages that do not contain it.

It also builds an index based on the documented methods, and the glossaries defined through all the pages, so it simplifies a lot the search of a term.

And finally, it lets us use (with very few modifications) the py3k documentation theme, so that people won’t be lost :).

So, as you may already guess or know, I am currently porting the poezio documentation from AsciiDoc to Sphinx, and except porting the never-ending list of commands and configuration options, it is quite painless.

You can see the progress of my work here. My objective is to have the full documentation moved before the 0.8 release (although it isn’t scheduled yet). Or by the end of next week.

EDIT: It’s now done, it looks quite good.

If you have remarks or suggestions concerning this article, please by all means contact me.