How does rclcpp convert its documentation from Doxygen to Sphinx?

asked 2023-07-31 05:59:15 -0500

hwhsu1231
1 ●2 ●2

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?

answered 2023-07-31 07:27:27 -0500

danzimmerman
337 ●3 ●25 ●13

updated 2023-07-31 07:28:49 -0500

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_p...

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...

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.

edit flag offensive delete link

Comments

Got it. Thanks for your explanation.

hwhsu1231 ( 2023-07-31 09:05:33 -0500 )edit

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.

hwhsu1231 ( 2023-07-31 09:07:35 -0500 )edit

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

danzimmerman ( 2023-07-31 21:44:38 -0500 )edit

add a comment

How does rclcpp convert its documentation from Doxygen to Sphinx?

Question

1 Answer

Comments

Question Tools

Stats

Related questions

How does rclcpp convert its documentation from Doxygen to Sphinx? edit

Question

1 Answer

Comments

Question Tools

Stats

Related questions

How does rclcpp convert its documentation from Doxygen to Sphinx?