Has anyone used Sphinx to document a C++ project? [closed]

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 bottomline is:

1. not yet fully usable
2. but keep watching
3. and, most importantly, consider devoting some time yourself ifyou are currently looking for a valuable OSS project that deservesyour 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 causeerrors in the sphinx parser, but make no trouble if I test themin 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 supportfor addressing functions with the same name in different classes and/or namespaces and/or doxygen xml output files. But showing of or linking toone specific of 10 overloaded constructors in a single class seemsinfeasible ATM. In the reference/linking case, there even is a parallel(maybe temporary) limitation on the sphinx level which breathe may or may notbe 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'sxml output. That should not be understood in such a way that it willexactly 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 andopen up quite a cool road. So it is worth watching just because of thepotential 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 convinceyour boss that breathe would suit him, or have some free time and arelooking 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-likestructure 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 anaffinity to sphinx, and when breathe is fully there, you are prepared tojump on. But again: consider showing breathe some love if it fits your agenda.

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_architectureDetailed Designs================..  toctree::    :maxdepth: 3    design/indexInstallation and Operations===========================.. toctree::   :maxdepth: 1   deployment/installation   deployment/operations   deployment/support   deployment/load_test_results   deployment/reference   deployment/licensingProgramming 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/

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