Automate generation of reference docs with doxygen and breathe

[dean0x7d]

This is an effort to update and complete the API reference docs. Keeping the docs together with the code should help the docs stay up to date. This PR puts an automated system in place: 1. Doxygen grabs the docs by parsing the headers and generates xml output. 2. Breathe provides new sphinx directives which read the xml files.

So far, I've only ported and updated the existing classes/functions from the reference page. This is to get a sense of what it would look like and see if this should move forward. A preview of the output is available here: http://pybind11-breathe.readthedocs.io/en/latest/reference.html

Documentation format: The doc comments can be written in reStructuredText or doxygen formats. I copied the existing docs from the .rst file and kept the original reST format. But I don't have a strong preference either way.

For reST, a downside is the need to surround comments with \rst \endrst in order to enable cross-references and directives (.. code-block::, etc.). For simple plain-text doc comments, the extra \rst \endrst can be omitted. I've set the default reST `text` role to any. This makes `object` work just like :class:`object` and `object::release` is equivalent to :func:`object::release`. This makes for easier reading and writing of doc comments.

The standard doxygen format can also be used if preferred. Let me know if this is the case.

Doxygen version: A fairly new version of doxygen is required to parse some of the more obscure C++11 in the headers (ref qualifiers). Unfortunately, the latest version (1.8.13) has a nasty segfault issue, so the requirement is either 1.8.12 or the latest 1.8.14 dev build (brew install --HEAD doxygen works nicely on macOS). Appropriate versions are installed on readthedocs and travis.

Let me know what you think. If this looks OK, it can be expanded to cover more code.

[loriab]

Hi @dean0x7d, it looks like one pybind11::pybind11 to pybind11::module conversion got missed at https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in#L74 . Do you want to add it to a future commit of this WIP PR, as it hardly seems worth its own commit?

[dean0x7d]

@loriab Good catch, thanks. But it's probably best not to bury an unrelated fix in this PR. Maybe submit a separate PR or perhaps @wjakob can just commit it directly?

[loriab]

Thanks for advice. Made PR so it can be aboveboard.

[wjakob]

I think this looks fantastic. Having more comments in the header files will surely also be appreciated by people reading the code. The \rst tags etc. don't bother me at all.

[dean0x7d]

The reference docs now cover more code. There's lots more that can still be added, but I think this should be enough for this PR -- to establish the general framework and have some doxygen/breathe examples for reference when documenting new features.

Small note: Doxygen's log contains a few warnings. It gets a bit confused by the DEPRECATED macro during parsing, but the warnings are generally harmless. These can be worked around using Doxygen-specific #ifdefs, but I don't think it's really worth it.

Let me know if there's anything about the style or organization that should be changed. Otherwise, if this looks OK, I think it's good to go.

[jagerman]

The standard doxygen format can also be used if preferred. Let me know if this is the case.

Will it support regular doxygen format now, or would I have to use \rst style to add to the API docs?

[dean0x7d]

\rst is only needed if the doc comment contains some kind of reST/Sphinx markup or directives. Doxygen commands like \brief, \param, \return are supported, but I guess it would be nice to settle on one or the other. A pure Doxygen style would make it possible to also generate the full docs using Doxygen alone. On the other hand, the reST style helps with Sphinx integration: pages or sections of the tutorial docs can be referenced using :ref: markup.

[wjakob]

Merged! Sorry for the delay, I was completely swamped this last month.