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

Question

Sphinx is a new documentation tool for Python. It looks very good. I am wondering:

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

Answer 1

As mentioned here and here ,

• Native C ++ support for Sphinx is associated with highlighting / formatting / link, and not with extracting documentation inside the code.
• breathe developed from the discussion that chrisdew refers to

[Edit added below]:

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

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

Let me clarify these points:

• I had problems with:

  • Latex markup in doxygen markup (not currently supported, but should be easy to implement)
  • Some parser errors (several function header definitions) that seem to cause errors in the sphinx parser, but don't cause problems if I test them directly in sphinx C ++ code blocks. I do not know what the difficulty of fixing is, but this is a serious functional switch.
  • Some problems 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 or linking to one of 10 overloaded designers in one class seems like an invalid ATM. In the case of linking / linking, there is even a parallel (possibly temporary) limitation of the level of the sphinx, which can breathe, or may not be able to get around.
  • Currently it is not possible to show all (or all protected / private) members of a class. It was somehow introduced with a different fix and should really be trivial for repairs.

  • More generally, keep in mind that this ATM is the bridge to Doxygen's xml. This should not be understood in such a way that it accurately displays what doxygen does, only with the above limitations. Rather, it offers you exactly, no more, no less, opportunities

    • upload everything in one doxygen domain to one giant page
    • show specific functions, members, structures, enumerations, typedefs or classes, which, however, must be specified manually. There is a fork on github that may or may not solve this general conceptual problem, but there are no hints for the future.

• In my opinion, a fully functional smoke will fill a large gap and open a pretty cool road. Therefore, it is worth looking only because of the potential gain.

• With sadness, it seems that support through the creator will greatly decline in the future. Therefore, if you work in a company and can convince your boss who is breathing, will suit him or you will have free time and looking for a really valuable project, think about giving him a fork!

As an end pointer, also take a look at the doxylink contrib project for sphinxes, which can provide an intermediate solution: create a surrounding textbook structure that references the old docigenic documentation (css-style) (I think you could even enter the same title in the sphinx , and on top of the doxigenic documentation for look'n'feels). So your project is an affinity for the sphinx, and when you breathe completely there, you are ready to jump on. But then again: think about showing how some kind of love breathes, if it matches your agenda.

Answer 2

First save the two source and build directory trees. Put source under version control. Do not put build under version control, rebuild it as part of the installation.

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

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

Organize your documentation in a well-planned tree. Some sections need "index.rst" for this section, some do not. It depends on how the partition is "offline."

Our top level index.rst as follows.

 .. 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 $ 

Please note: we do not include the API, we just reference it with a regular HTML link.

Sphinx has a very cool add-on called the auto-module, which selects docstrings from Python modules.

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

Answer 3

See http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html for an XML approach.