Large Problems in Django, Mostly Solved: Documentation

Feb 05

Large Problems in Django, Mostly Solved: Documentation

[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.

Comments

1 Carl Meyer says...

For small projects where the documentation is short enough that it's reasonable to keep it in one file, I think putting it all in a README.rst and sticking the entire thing in the PyPI long-description is more usable than Sphinx docs. It makes everything immediately accessible and searchable on the very first landing page, whether that's Bitbucket, Github, or PyPI. So I'm not quite in the "just use Sphinx" camp.

That said, lots of projects have/need more docs than this (and frankly, a couple of mine might be moving into that category shortly). In which case Sphinx is the obvious (really, only) choice.

Posted at 3:30 p.m. on February 5, 2010

2 Yuri van der Meer says...

I recently started using Sphinx for a rather big Django project and have been loving it from the start. The documentation is built along with the software as part of our continuous integration process, so the HTML documentation is available on the build server a few minutes after we check in new reST sources into SVN.

Also, I love the fact that with the LaTeX builder, you can specify different document roots. For instance, we use a single Sphinx "tree" for both technical and functional documentation, but we can generate separate PDFs for both by configuring two LaTeX output documents.

Posted at 7:46 p.m. on February 5, 2010

3 Klaus Blindert says...

Thanks for the interesting series.

I was aware of south and sphinx, however I missed haystack and piston, so there's something more to learn for me. Good!

Do you consider django-cms and pinax big problems solved as well? These projects certainly provide at least a starting point for their web app niches.

Posted at 11:57 a.m. on February 6, 2010

4 John says...

reST is alright, but I still prefer working with Markdown.

Incidentally, I notice that the comments here support Markdown. :)

Posted at 6:18 p.m. on February 6, 2010

5 cheap latisse says...

Internet based cash advances

Posted at 1:47 p.m. on May 3, 2010

6 porno says...

Awesome post! Nothing more to explain.

Posted at 9:07 a.m. on May 29, 2010

7 cndeueujs says...

Watch Twilight Eclipse Online 342fvydvgf http://identi.ca/watchtwilighteclipseonlinefree86 nduisy8

Posted at 7:23 p.m. on July 9, 2010

8 Grants For Older Students says...

My School grants can help individuals go to school without financial burden of paying back school debt.My School grants help students pay for education. Financial aid including grants for African-Americans, Native Americans, Asian- Americans & Hispanics is the best way to afford school and college tution fees.

Posted at 6:44 a.m. on August 30, 2010

9 Addellagoable says...

I would have to say my favourite celebrity is <a href=http://stars-celeb.blogspot.com/2010/09/kim-kardashian-regrests-sextape.html>Kim Kardashian</a> What do you all think of her? The girl is very exotic to me. Loving ericholscher.com by the way, funnest website I've found in ages. Anyone know where I can get more photos of her? So far I just have these two (<a href=http://movievine.romanzaclub.com/2010/09/27/kim-kardashian-sextape-regrets/>Kim Kardashian</a>)

Posted at 2:58 a.m. on September 30, 2010

10 acclaims insurance boston says...

Great blog post, I have been after that?!?

Posted at 10:46 p.m. on October 14, 2010

11 Diabetes in dogs says...

thanks for sharing these tips with us

Posted at 8:12 a.m. on October 27, 2010

Surfing in Kansas