This past week or so, I've spent a lot of time with Taskotron working on a setup tutorial and looking for documentation tools. With Taskotron being a new project, QA was in need of a good toolset for handling documentation. In the python world, Sphinx rules documentation - but it's pretty python centric, so I thought I would hunt around for some other options.

Currently Fedora QA has a couple places for documentation, all revolving around the wiki. Ideally, all the documentation for Fedora would live in one place. However, the wiki doesn't lend itself to 100% of documentation cases. It's great for data that doesn't change often, but becomes a pain to manage when things need to be updated.

Requirements

For QA Development projects we only had a few requirements:

• Output in HTML
• Build in CI
• Be able to do dev docs, task author docs and user docs
• rst input preferred

The idea is to be able to write documentation and manually update it as little as possible. This task becomes significantly more complicated when you throw in the multiple audiences - dev, task authors and end users. This means at least three different bases of documentation. With a wiki, pretty much all of your documentation needs to be updated manually - a severe problem if you have three versions of something to update.

The bear of updating documentation for a project is during a refactor - when all your code examples change. So ideally a solution would be able to update docs from source to minimize manual touchups when code changes.

Sphinx

Since Taskotron is written in python (as are a lot of applications used within Fedora QA), Sphinx was an obvious candidate. It was originally created for python documentation, but also supports other languages through extensions. Sphinx takes ReStructuredText as input and is capable of outputs in several formats. It is also capable of importing your python modules and extracting the docstrings, automatically creating API docs (from specially formatted docstrings). Sphinx was meant for "handwritten" docs, but is often used to provide a shiny web-based portal for API documentation. This brings us to Dexy.

Dexy

Dexy is a newer project aimed at producing easy to manage technical documents. It accepts a variety of inputs and spits out a variety of outputs. Dexy uses something called 'filters' to handle these inputs - transforming input into the desired output - and there are filters for a variety of languages. From a functional standpoint, Dexy is very similar to Sphinx. But it's use of filters makes it really easy to add other languages to documentation projects without having to mess with extra extensions.

Comparison

Dexy and Sphinx both fill similar gaps and provide similar functionality. Both use jinja for templating. Both are actively under development. Both can work with multiple languages and both are written in python. The real clincher for me was the ease of templating. Sphinx has a lot of functionality built in, allowing you to easily create documentation for your project that matches what python developers are used to in documentation. Dexy templates, on the other hand, are as simple as adding '{{ content }}' to an existing template.

From my perspective, sphinx/dexy can be compared to django/flask. One has a lot of batteries included while the other gives you the tools to build out exactly what you want. At the end of the day you could use either tool and end up at the same result.

Conclusion

My preference after comparing the two tools is for dexy. There isn't a large difference between the capabilities of the tools - but I found dexy a bit easier to use. Splitting sections of a tutorial out was easy, and allows for a nice modular design to docs.

It would require minimal extra effort for a project to pull source examples directly from the codebase, just extra comments in the code. Sphinx can do the same, but I felt that dexy had better support for a variety of outputs and languages.

// Roshi