[FM Discuss] Python document generation tool; might be worthwhile studying for comparison

[Janet Swisher]

On Sun, Oct 25, 2009 at 6:48 AM, Andy Oram <andyo at oreilly.com> wrote:
> I heard about this from a colleague and thought we might learn from what they do and why; just passing on the summary he gave me.
>
> ---
>
> http://sphinx.pocoo.org/
>
> Latest features I've found useful:
> - Cross-site referencing (makes it a snap to refer to docs on a
> related project in another location)
> - Diagramming extension
> - Automatic PDF generation
>
> The extensions are incredibly useful:
> http://sphinx.pocoo.org/extensions.html


I'm fairly familiar with Sphinx, as I used it in my previous job (left
there in mid-July). The straight-to-PDF functionality is new -- you
used to have to go by way of LaTeX, which affected the look of the
output.

I think the extension mechanism has been key to its spread and
adoption in the Python community. If the existing code doesn't do
quite what you need, it is only a Small Matter of Programming to make
it do so. Sphinx was originally designed fairly specifically for
generating the official Python documentation (and the default
templates, etc. reflect that purpose), but others have adapted and
extended it for a variety of other purposes.

It's also great that it supports real "book-oriented" features like
cross-references, index terms, and hierarchical structure.

--Janet