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.

Answer 3

As mentioned here and here,

• Sphinx native C++ support is related to highlighting/formatting/referencing, not in-code documentation extraction
• breathe has developed out of the discussion that chrisdew referenced

[Edit inserted below]:

I tested the doxygen+breathe+sphinx toolchain on a multi-10k C++ library consisting of 10 different modules/domains. My bottom line is:

1. not yet fully usable
2. but keep watching
3. and, most importantly, consider devoting some time yourself if you are currently looking for a valuable OSS project that deserves your time.

Let me elaborate these points:

1. I had problems with:

   • Latex markup within the doxygen markup (not supported currently, but should be easy to implement)
   • Some parser errors (several function header definitions), which seemingly cause errors in the sphinx parser, but make no trouble if I test them in sphinx c++ code blocks directly. No idea on the difficulty of fixing, but this is a serious functionality breaker.
   • Some trouble with overloaded identifiers. There seems to be some support for addressing functions with the same name in different classes and/or namespaces and/or doxygen xml output files. But showing of or linking to one specific of 10 overloaded constructors in a single class seems infeasible ATM. In the reference/linking case, there even is a parallel (maybe temporary) limitation on the sphinx level which breathe may or may not be able to work around.
   • Currently there is no way to show all (or all protected/private) members of a class. This was somehow introduced with another fix and must be really trivial to repair.

   • In a more general sense, be aware that it ATM is a bridge to Doxygen's xml output. That should not be understood in such a way that it will exactly output what doxygen does, just with the above limitations. Rather, it offers you exactly, not more, not less, the possibilities to

     • dump out everything in one doxygen output domain onto one giant page
     • show specific functions, members, structs, enums, typedefs, or classes, which however must be specified by hand. There is a fork on github which may or may not want to address this overall conceptual issue, but no hints for the future there.

2. In my opinion, a fully functional breathe would fill a major gap and open up quite a cool road. So it is worth watching just because of the potential gain.

3. It sadly seems that maintainance through the creator will go down severely in the future. So if you are working in a company and can convince your boss that breathe would suit him, or have some free time and are looking for a really valuable project, consider to give it a fork!

As a final pointer, also note the doxylink contrib project for sphinx, which may provide an intermediate solution: build up a surrounding tutorial-like structure which references the (css-style matched) old doxygen documentation (i think you could even inject the same header into sphinx and on top of the doxygen documentation for look'n'feels). That way, your project keeps an affinity to sphinx, and when breathe is fully there, you are prepared to jump on. But again: consider showing breathe some love if it fits your agenda.