Surfing in Kansas

[This is part of the Large Problems in Django Series, see previous entries about: APIs, Search, and Database Migrations]

Django is well known across the open source community for it's stellar documentation. While the tech behind the documentation plays only a little role in how good it is, the tools behind both Python and Django's documentation is Sphinx. Luckily, we can all use Sphinx to document our projects, and I'd like to talk a little about why you might want to.

Why use Sphinx

Network Effects

One of the big reasons is because it is becoming the standard documentation tool in the Python community. Once your projects documentation is in Sphinx, most everyone will know how to contribute to it. You will also be able to contribute to other projects easily as well. You can look through the Python and Django docs for examples of how to do neat things, and it is really the best solution to the problem.

It uses Restructured Text

If you are writing plain text about python, more than likely you should be using Restructured Text. All docstrings are parsed for it, and you only need to learn this one markup language for all of your plain text needs. It even works great for blog posts, with most Django blogging engines supporting it. It is also easy to extend, and is generally a useful thing to know how to do.

Write once, compile to HTML, PDF, etc.

By writing in Restructured Text, you write your documentation with metadata about what all of your text means. This then allows it to be transformed intelligently into other formats. This is how Django can provide HTML and PDF versions of the documentation all from the same source format. By rendering through LaTeX, you are given a large amount of flexibility in the style of your PDF output, allowing for really nice designs with a little effort.

Your docs are beautiful

Sphinx has native support through Pygments for syntax highlighting most languages that exist. It also ships with support for themes, with the community providing themes out of the box to make your documentation look great. This is another place where having a critical mass of people behind the project makes your docs better.

Cross References

With simple markup rules applied to your documentation, you get indexes and cross referencing for free. This makes your documentation much more discoverable, and useful for people who are browsing it. The Django documentation makes extensive use of this, making it easy to jump to the definition of a setting where ever it is referenced for example.

Lots and lots more.

Please just go look at Sphinx, and read a little more about it. The Overview at the Sphinx page gives you a nice example of actual Sphinx docs, and points to lots of little tidbits of information. Sphinx has made documenting your project a real joy, and I can't recommend it enough.