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?

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.

Comments

[user1488804]

Thanks for your fast response. I have had a look at Doxygen before and am aware of the commenting style required to generate documentation from code using it. Before I use Breathe, however, I would like to see if Sphinx can be used alone to produce the desired documentation. It works great at making html outputs from reST formatted text, but all I'm struggling with is using the sphinx-apidoc..... command to produce documentation from c++ code.

[user1488804]

I know it is supported, but I'm just having trouble using it in conjunction with the directives that you're supposed to insert into the code for the comments to be extracted. So I guess what I'm looking for is a guide on how to use the directives for the c++ domain inside the code and then use the sphinx-apidoc command to extract the comments.

[Jonas Schäfer]

@user1488804 from my knowledge, sphinx is by default Python only. You need extensions to get other languages into it. Python support is easy to do, as you can just do introspection on the objects to get the docstring. You can include reST code into doxygen comments by using \rst and \endrst with breathe.

[user1488804]

if you check the link I posted above from the sphinx website (sphinx.pocoo.org/latest/domains.html) it states that extracting things from C++ code is possible (provided you change the domain to 'cpp' as apposed to 'py'). It even gives descriptions of the directives you can use. The trouble I'm having is that I don't know how to use them properly.

[Jonas Schäfer]

I cannot see how it states to be able to extract from c++ code; It can create documentation for C++ code, and you can cross-reference it. I might really be blind right now though.

[user1488804]

Quoting the second paragraph in "it is now much easier to easily support documentation of projects using different programming languages..." (i.e. C++). I am someone with very little experience in this area so I might be misunderstanding what it is saying, but when it creates documentation for C++ code, isn't it lifting sections from the code, such as comments and the like?

[Jonas Schäfer]

No, it is not. This is referring to the possibility of using multiple languages in the same project and separate the namespaces of the languages properly by using sphinx/reST domains. The „different“ is really referring to „multiple different languages in the same project“ rather than „languages different from python“. Sorry.

[user1488804]

But these different languages refer to c++, java and so on. So why does this prevent you from using sphinx to produce documentation from c++ code. I mean, what do you use the directives shown for if it's not generating this documentation?

[Jonas Schäfer]

You can create documentation. But not in an automated fashion (i.e. having sphinx reading the sources and creating documentation in an autodoc like fashion). You have to create your documentation manually if you do not want to use breathe, i.e. writing .rst files with reST commands separated from your source.

[user1488804]

Oh I see. That's a shame. But then what are all those directives used for (like .. py:function:: and .. cpp:class::)?

[Jonas Schäfer]

@user1488804 I edited both your question and my answer to reflect this discussion. Please review the edit.

[user1488804]

Ok. So you're saying that you have to manually insert these directives into a separate file from your source code in order to pull the desired parts from it into the generated documentation. So for example, the command bool namespaced::theclass::method(int arg1, std::string arg2) would bring up the description of that method by pulling it from the source file and inserting it into the new document?

[Jonas Schäfer]

No it would not. Again: Sphinx can not read c++. You have to write your documentation all in the separate files except if you're using a helper like breathe.

[user1488804]

Arrrrg I appear still not to understand the problem then. Could you please explain what those directives (like the one I posted in my last reply) do, and how they are used? Thanks for baring with me by the way. I appreciate the help

[Jonas Schäfer]

@user1488804 Really, do some trial and error by setting up sphinx and playing around with the directives using the manual. I'm afraid I cannot explain it better than you'll learn it when just trying.

[user1488804]

I realize this is usually the better approach but before posting I did try and using some basic directives in conjunction with sample code. I did this for c++ files and python files, and received no results in the case c++ and only blank (apart from header) files with python. Here I am referring to the use of the sphinx-apidoc command. I am pretty comfortable with most of what else sphinx has to offer (including reST markup and converting to html/pdf), and have read a lot of documentation on these topics over the last week. But I am still having trouble with the autodoc side of things.

[user1488804]

I haven't even seen these directives before, and unfortunately I'm finding it very hard to understand them. I apologize if you're finding it frustrating that I'm not getting it, but I appreciate your persistence. With reference to the sentence in your edit of the initial reply (specifically the paragraph after the c++ directive block) what do you mean by writing the documentation yourself. Are you saying that 1. You have a source c++ file. 2. You write a separate file in reST mark-up with all the directives and other text.

[user1488804]

3. Using the sphinx-apidoc command you generate documentation that describes your code and so on, based on the directives you used in your .txt file. If this is not the case then I do not understand what the directives are for.