Has anyone used Sphinx to document a C++ project?

Question

Sphinx is a new documentation tool for Python. It looks very nice. What I'm wondering is:

• How suitable this is for documenting a C++ project?
• Are there any tools for converting existing documentation (e.g. doxygen) to Sphinx format?
• Are there online/downloadable examples of C++ projects that use Sphinx?
• Any tips from anyone who has used Sphinx?

Answer 1

First, keep two directory trees, source and build. Put source under version control. Don't put build under version control, rebuild it as part of installation.

Second, read http://sphinx.pocoo.org/intro.html#setting-up-the-documentation-sources.

Use the sphinx-quickstart to build a practice documentation tree. Play with this for a few days to learn how it works. Then use it again to build the real thing in SVN directories.

Organize your documentation in a well-planned tree. Some sections need an "index.rst" for that section, some don't. It depends on how "stand-alone" the section is.

Our top-level index.rst looks like this.

.. XXX documentation master file, created by sphinx-quickstart on Wed Dec 31 07:27:45 2008.

..  include:: overview.inc

.. _`requirements`:

Requirements
============

.. toctree::
   :maxdepth: 1

   requirements/requirements
   requirements/admin
   requirements/forward
   requirements/volume

.. _`architecture`:

Architecture
============

.. toctree::
   :maxdepth: 1

   architecture/architecture
   architecture/techstack
   architecture/webservice_tech
   architecture/webservice_arch
   architecture/common_features
   architecture/linux_host_architecture

Detailed Designs
================

..  toctree::
    :maxdepth: 3

    design/index


Installation and Operations
===========================

.. toctree::
   :maxdepth: 1

   deployment/installation
   deployment/operations
   deployment/support
   deployment/load_test_results
   deployment/reference
   deployment/licensing

Programming and API's
=====================

..  toctree::
    :maxdepth: 2

    programming/index

**API Reference**. The `API Reference`_ is generated from the source.

.. _`API Reference`: ../../../apidoc/xxx/index.html

..  note::
    The API reference must be built with `Epydoc`_.

    .. _`Epydoc`: http://epydoc.sourceforge.net/

Management
==========

.. toctree::
   :maxdepth: 2
   :glob:

   management/*


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

SVN Revision
============

::

    $Revision: 319 $

Note, we don't "include" the API, we just reference it with an ordinary HTML link.

Sphinx has a very cool add-on, called automodule, which picks the docstrings out of Python modules.

Update As of Sphinx 1.0, C and C++ are supported. http://sphinx.pocoo.org/

Answer 2

Have a look at http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html for an XML approach.