Is Sphinx already suitable for C++ documentation?

Question

I want to try out documentation generators for a new project in C++. I think my options are either Doxygen or Sphinx. Since I have projects in Python for which I'd like to use Sphinx, I wonder whether Sphinx is the right choice for C++ as well. The Sphinx website states that C++ is supported, but I could not find a document to get me started with C++ documentation.

A similar question has already been discussed on Stackoverflow and the main answer concludes:

not yet fully usable,
but keep watching

Since the discussion is well over a year old, I wonder whether this conclusion is still valid. Should I choose Doxygen over Sphinx for my C++ documentation?

Solution 1

Sphinx cannot extract documentation from C++ sources in and by itself. However, there are extensions, most notably Breathe, which utilize Doxygen to extract documentation from C++. I've not tested any of these.

Solution 2

For C++ Doxygen is very good; Sphinx support of C++ is done via Doxygen (using Breathe).

You want to have only one tool for the two languages, to improve maintainability. Doxygen can generate a documentation from Python code, so I advise you to use Doxygen for both sources, if possible. Here is a tutorial for Doxygen and Python.

Comments

[lucasg]

I do not know about Sphinx, but I think Doxygen is really a great tool ! What issues did you find about Doxygen ?

[clstaudt]

@georgesl The only issue I have with Doxygen at the moment is that I am going to use Sphinx for my Python projects and want to avoid using two different documentation systems. It probably takes time to get started with each one, and getting used to the syntax.

[Benjamin Lindley]

On the right hand sidebar on their website, there is a link to a Google Group and a FreeNode chat handle. Have you tried those? I'm not necessarily saying this question doesn't belong here, just that I would think you'd be more likely to get an informed response there.

[Matthieu M.]

Sphinx is good for documentation of any kind, so what do you mean specifically by C++ documentation ? Automatic extraction of comments ? Automatic extraction of classes and functions ? There is a lot that Doxygen does and whether you are looking for a full replacement or just want some features is not clear.

[clstaudt]

@MatthieuM. You're correct, but since I have not used a documentation generator before, I cannot specify my requirements exactly. At least, I want to write documentation in my comments and have it extracted and formatted. Other features are optional. If I had very specific requirements I probably could research this myself and would not need input from more experienced users like you.

[Matthieu M.]

@cls: Actually, there is a debate practice wise of what should be extracted and what should be documented apart. It makes sense to automatically extract class/functions, and this let you build a searchable index and so. However, it's not clear whether documentation should also be there. Making it a separate document allows less technical people to use them, and it's also easier in source management to have different types of document be overviewed by different people. Finally, lengthy explanations in the code eat up screen estate.

[lunaryorn]

@cls Stick to the standard tools of a language. In C++, that is doxygen, despite all its problems. You're using two vastly different languages anyway, so you should be able to cope with two mildly different tools.

[Synxis]

@lunaryorn I disagree. You should choose the tools that are the most suited to your project/problem. And C++ does not have a "standard" documentation tool.

[lunaryorn]

@Synxis A language's standard tools are likely best suited for projects or problems in that languages. That's why the became de-facto standard tools in the first place. Surely none declared Doxygen to be the standard documentation generator for C++, but nonetheless everyone uses it, simply because it's the best (actually the only) documentation generator for C++.

[Morwenn]

I couldn't find an example documentation out of the box so I decided to post mine here: I began to document a C++ library of mine with Sphinx. It's hand-rolled, no auto-generated documentation from the code, but it at least showcases what you can do by hand with Sphinx to document a C++ project without much effort.

[Isaac Pascual]

My experience over years with Doxygen and C++ is that is the only one but fail a lot of times and is not as usable as I want. The problem is that there are not an alternative. I hope somebody working on a clang alternative and come near future.

[lunaryorn]

I have in years of Python programming never seen any Python project using Doxygen. It's absolutely a non-standard tool in the Python community, and it is unlike that you'll find much help should you ever have problems.

[Synxis]

Your argument is 'Doxygen is bad for Python because nobody uses it'? Sorry, but this is not true. For example, see code.foosel.org/doxypy , stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks , engtech.wordpress.com/2007/03/20/… (so there are people interessted in Doxygen with Python).

[lunaryorn]

Some Google results don't really defeat my statement that it is a non-standard tool in the community. Widespread use of Doxygen in important projects would, but there is none. No considerable Python project is using Doxygen for documentation, or has done so in the past. Heck, not even Zope does…

[Synxis]

You're right, no really big Python project uses Doxygen. But with your reasoning, only pydoc should be used, and not Sphinx/Doxygen/epydoc...

[lunaryorn]

That is not my reasoning. I did not say what should be used. I assessed what is actually used, based on my personal experience and observations. Sphinx and epydoc are widely used among Python developers – epydoc's usage decreases, though – and can hence be considered de-facto standard tools in Python. Pydoc is a different tool for a different use case, and also standard among Python developers.

[Niklas R]

Seems like I still need to use the weird Doxygen syntax if I use Breathe. :-/

[Erik Aronesty]

See breathe.readthedocs.io/en/latest, you don't need to use doxy syntax.

[Akib Azmain]

There's also a new player named antidox, which is still in the alpha development phase.