Using Sphinx-apidoc to generate documentation from C++ code

Question

There have been a couple of threads on this topic in the past that claim Sphinx doesn't support this at all. I had my doubts but either it has been updated since or the documentation for it was quite well hidden, because here is a link on the website stating otherwise: http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cpp-domain

Anyway, I'm new to Sphinx but am trying to use it to (eventually) automate documentation using some text from some source C++ code. So far I haven't been able to get anywhere when using the sphinx-apidoc -o ... command. An almost blank document is created. I'm probably not using the right directives, since I don't know how - the supporting documentation hasn't been able to help me.

Can anyone provide some assistance with the basic steps needed to get it working? If it is not possible to auto-generate documentation from C++, what are the C++ domains for and how to use them?

Answer 1

On auto-generating C++ documentation:

After reading up on how to use sphinx at all, you should have a look into breathe:

Breathe provides a bridge between the Sphinx and Doxygen documentation systems.

It is an easy way to include Doxygen information in a set of documentation generated by Sphinx. The aim is to produce an autodoc like support for people who enjoy using Sphinx but work with languages other than Python. The system relies on the Doxygen’s xml output.

So additionally, you'll need to follow Doxygen commenting style and even setup an doxygen project. But I tried that and it works really well after the initial setup took place. Here is an excerpt of our CMakeLists.txt which might give you an idea on how sphinx and doxygen work together:

macro(add_sphinx_target TARGET_NAME BUILDER COMMENT_STR)
    add_custom_target(${TARGET_NAME}
    COMMAND sphinx-build -b ${BUILDER} . sphinx/build/${BUILDER}
        WORKING_DIRECTORY docs
        DEPENDS doxygen
        COMMENT ${COMMENT_STR}
    )

endmacro(add_sphinx_target)

add_custom_target(doxygen
    COMMAND doxygen docs/doxygen.conf
    COMMENT "Build doxygen xml files used by sphinx/breathe."
)

add_sphinx_target(docs-html
    html
    "Build html documentation"
)

So after initial setup, essentially it boils down to:

1. build doxygen documentation with doxygen path/to/config
2. cd into the directory where the sphinx configuration is.
3. build sphinx documentation with sphinx-build . path/to/output

On the c++ domain:

Sphinx is a „little bit“ more than a system to auto-generate documentation. I would suggest you have a look at the examples (and consider that the sphinx website itself is written in sphinx reST code). Especially click the Show Source link on many sphinx-generated pages.

So if you cannot generate documentation automatically for a project, you have to do it yourself. Basically sphinx is a reST to whatever (LaTeX, HTML, …) compiler. So you can write arbitrary text, but the advantage is that it has a lot of commands for documenting source code of different languages. Each language gets its own domain (prefix or namespace) to separate the namespaces of the different languages. So for example I can document a python function using:

.. py:function:: Timer.repeat([repeat=3[, number=1000000]])
    Does something nasty with timers in repetition

(source)

I can do the same using the cpp domain:

.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)

   Describes a method with parameters and types.

(source)

So if you want to document your c++ project without doxygen+breathe but with sphinx, you'll have to write the restructured text files yourself. This also means that you split the documentation from your source code, which can be undesirable.

I hope that clears things up a bit. For further reading I strongly suggest that you have a good read on the sphinx tutorial and documentation until you understood what it actually does.