Sphinx – official Python documentation tool

EDIT: Sphinx’s gone public: http://sphinx.pocoo.org/

While searching for an ideal documentation tool for build.py, i’ve checked pydoc, epydoc and many many more. Two days ago, I’ve landed on Python development version documentation site (http://docs.python.org/dev). Engine has been totally reworked (besides, new look n’ feel is simply beautiful). Now, it sits on Sphinx, which is boosted reStructuredText engine with syntax highlighting, Table of Contents generation and a bunch of another useful gadgets.

I saw it nearly perfect for my purposes, as I don’t like docstrings and I’ve had some good experiences with text markup syntax (Markdown, particularly). The only problem is, Sphinx isn’t available as a standalone package – it’s bundled with main Python branch. Hence, there’s a solution how to incorporate Sphinx into your projects.

At first, checkout python from svn server (you could checkout only Doc dir, but I’m not sure whether it breaks any internal dependencies), then cd into Doc dir and run make:

svn co http://svn.python.org/projects/python/trunk # checking out Python tree
cd trunk/Doc # moving into Documentation directory
make html

Makefile included within Doc directory with checkout proper Sphinx stuff, like syntax highlighting, reST parser etc. It will then start the documentation creation process. Stop it, cause probably you don’t need a local Python documentation mirror.

To use Sphinx in your apps, copy tools directory (in trunk/Doc) to your project and conf.py file to your documentation directory. You need to edit conf.py and edit/delete some field in order to not getting attacked by army of errors and warning.

After that, consult Sphinx usage by:

python tools/sphinx-build.py –usage

For example, you could use:

python tools/sphinx-build.py -b html mydocs myproject/docs # conf.py should be in mydocs dir

You should inspect http://docs.python.org/dev/documenting how to use reST syntax properly (and what are these additional features).

There’s also a need to take care of tools/sphinxext directory. As you can see, there are templates for main page, sidebar and etc.

Happy documenting!

---

Possibly related posts: (automatically generated)

• Sphinx Documentation System