What tools can be used to produce beautiful documentation for a Python project?

Question

I'm working on an open-source project called python-graph. We've come to the point where our APIs are stabilising and we've realised that we need some user docs. We already have automatically generated Epydoc API reference documents, however I want to I want to create something more useful for beginner programmers who find the auto-generated doc formats somewhat impenetrable.

I'd like our documentation to be accessible to first-time programmers - especially undergraduate level and people from a non-mathematical background.

Mark Pilgrim seems to create some of the best documentation i've ever read. We want to make a document that works much the same way that his online "Dive into Python" project works.

My question: How did he do this? Is there a content management system which is geared towards building documents like this? Is this LaTeX, and if so how he get the code highlighting so perfect? Furthermore, is there a way that we can reference code externally? I'd want to ensure that every example code we put into our docs is automatically tested for validity as our APIs evolve.

Thanks

Answer 1

I have been very impressed by results from Sphinx which seems to be getting more popular.

Edit: To make this more explicit, allow me to quote the key bullet points from the Sphinx home page:

• Output formats: HTML (including Windows HTML Help) and LaTeX, for printable PDF versions
• Extensive cross-references: semantic markup and automatic links for functions, classes, glossary terms and similar pieces of information
• Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
• Automatic indices: general index as well as a module index * Code handling: automatic highlighting using the Pygments highlighter
• Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules, and more

Answer 2

How about Sphinx, which is used for python.org and many other applications?

Answer 3

Dive into Python is a custom script. You can download the source from here: http://diveintopython.org/download/diveintopython-common-5.4.zip

I think that Mark spent a great deal of time on the documentation though - you might want to do something easier (like running Sphinx). Even Sphinx is pretty heavyweight.

I the documentation on projects like GraphViz - an easy to access set of examples, and code that can be pasted in, to recreate their results: http://www.graphviz.org/Gallery.php

Also, time box your documentation effort. You don't want to spend too much time getting it right. Just put out some tutorial scripts that show the users how to solve their problems.

Answer 4

In regards to the "How did he do that?" question: If the document is on the web in html, it is probably not LaTeX. LaTeX's end goal is printed documentation (pdf, dvi, or ps, for the most part). LaTeX source can be changed to HTML, but if you desire only HTML output, then LaTeX is certainly NOT the way to go.

Certainly Sphinx, and the rest of the python docutils, is your best bet. With docutils, you'll be able to make comments inside your source, then extract it and format it almost automatically. Python uses a plain text mark-up called ReStructured Text (often abbreviated "reST"). With your documentation in reST format, you'll be able to convert to LaTeX and HTML quite easily. With a bit of custom CSS I'm sure your documentation can look just as good as the Dive into Python documentation.

Answer 5

This other question/answer may also be of interest:

Can I document Python Code with Doxygen, and does it make sense?

Doxygen's pretty common in documenting other languages too. :)

Answer 6

Mark Pilgrim is writing Dive into Python 3 in straight HTML.