How does rclcpp convert its documentation from Doxygen to Sphinx?

Question

I accessed the latest rclcpp documentation through the link in the README of the ros2/rclcpp repository and found that it was built by Sphinx. Based on my understanding:

If a documentation is built by Sphinx, there should be a conf.py configuration file in its repository.
If a documentation is built by Doxygen, there should be a Doxyfile configuration file in its repository.
If a documentation needs to extract content from Doxygen and input it into Sphinx documentation, the Python package Breathe would be required.

However, I only see the Doxyfile in the ros2/rclcpp repository, and I do not find the conf.py file. How does rclcpp convert its documentation from Doxygen to Sphinx?

Asked by hwhsu1231 on 2023-07-31 05:59:15 UTC

Comments

Answers

It seems from this PR that the doc build is using Exhale.

There's a design doc here that discusses the requirements for the build tool:

http://design.ros2.org/articles/per_package_documentation.html#documentation-system

All packages will need a Sphinx configuration file. If a package doesn’t have one, the tool can use a default one. Python packages will need Sphinx directives explicitly integrated into the source code to produce API documentation (standard for Sphinx API documentation).

which I think is rosdoc2:

https://github.com/ros-infrastructure/rosdoc2#set-up-a-ros-2-package-to-be-used-with-this-tool

It aims to support two main cases:

zero configuration generation of C++ and Python API documents with a landing page for simple packages

custom Doxyfile (for C++) and Sphinx conf.py file for more extensively configured documentation

The goal for the first case is to allow almost no configuration in packages while still providing some useful documentation, even if there is no Doxyfile, Sphinx conf.py file, or any free form documentation.

So it looks like you can add a conf.py if you wish, but you don't need to.

Asked by danzimmerman on 2023-07-31 07:27:27 UTC

Comments

Got it. Thanks for your explanation.

Asked by hwhsu1231 on 2023-07-31 09:05:33 UTC

BTW, I'd like to ask if you know what the default conf.py used by rosdoc2 looks like?

All packages will need a Sphinx configuration file. If a package doesn’t have one, the tool can use a default one.

Suppose that there is a C/C++ project that originally used Doxygen to build its documentation, and I want to convert it into Sphinx documentation. Since I'm not very familiar with the usage and integration of Sphinx, Breathe, Doxygen, Exhale, and I think the structure of the Sphinx documentation currently used by rclcpp is quite simple and pratical, so I want to refer to it.

Asked by hwhsu1231 on 2023-07-31 09:07:35 UTC

No, I don't know how the default is handled.

Asked by danzimmerman on 2023-07-31 21:44:38 UTC