Over the last few months I've been intermittently working on the documentation system for my brother's voxel rendering project, PolyVox. We decided that we would use Sphinx, the project built for and used by Python for their end-user documentation.

We were already using Doxygen for the API documentation but we wanted a tool which was appropriate for a manual, tutorials etc. so we went for Sphinx. This is filling a similar role to Docbook in KDE but I much preferred the reST syntax to the verbose XML of Docboook.

Of course in the tutorials, since it's describing the API we wanted to be able to easily link from Sphinx to the Doxygen documentation so I wrote a Sphinx extension called Doxylink to allow the documentation to link directly to the API HTML pages by using to the tag file output by Doxygen. Using a notation like :polyvox:`Volume` it will create a HTML link to to correct page for the class 'Volume'. You can link to classes, enums, functions etc. and it supports linking to the correct overloaded version of a function. The full documentation is available at packages.python.org.

After a number of 0.x releases I've just released version 1.0 with a completely rewritten parsing system to try to account for some of the confusing C++ idiosyncrasies without having to resort to a full-blown C++ parser.