Sphinx is released!

written by Georg, on Friday, March 21, 2008 17:50.

I'm delighted to announce that the Sphinx library, used to build the new Python documentation (for 2.6 and 3.0), is now released for general use.

What is it?

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of multiple reStructuredText source files).

Its website is here.

What does it do?

Sphinx is not an API documentation generator like Epydoc. Instead, its focus is on hand-written documentation, such as the Python one.

Main output formats: HTML (including HTML Help) and LaTeX
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
Goodies such as changes overview, and external link checking

What else?

Various extensions are available and in development:

autodoc: pulls in documentation from docstrings that are written in reST, to avoid having to maintain multiple documentation locations
doctest: automatically tests snippets in the documentation in doctest fashion
coverage: documentation coverage checker

I'd like to thank everyone who has given it a try so far and provided me with valuable suggestions and patches: Uli Fouquet, Andre Roberge, Armin Ronacher, Tim Golden and Mark Summerfield.

Now back to documenting new 2.6 features...

Comments

Beautiful docs! How's the PDF version coming?

— Matt Doar on Saturday, March 22, 2008 0:03 #
hardcoded to jinja templates ? makes it hard for me to use it for Mako/SQLA documentation ;).

— mike bayer on Saturday, March 22, 2008 0:43 #
@matt: It's right there if you run pdflatex over the generated LaTeX.

If someone stops by and writes a builder that generates PDF directly, e.g. via reportlab, I'll certainly accept it :)

— Georg on Saturday, March 22, 2008 9:56 #
@mike: You can use a custom builder. Actually it should even be possible to just use the web builder and use the pickled data and use that one to generate the documentation in another application.

— Armin Ronacher on Saturday, March 22, 2008 10:34 #
Great work, bravo !

— Tarek on Sunday, March 23, 2008 9:25 #

Commenting is no longer possible.