With renewed activity around rosdoc2 (my PR got merged after 498 days!), and ongoing discussion about the state of documentation in ROS 2, I decided to look at ROS 2 package docs once again. This is also a followup to my older post on releasing a ROS package.


The tool responsible for generating ROS 2 package docs is rosdoc2. It is what runs on the ROS build farm whenever you update your package and have enabled the appropriate options in rosdistro/<ROS DISTRO>/distribution.yaml:

      type: git
      url: https://github.com/teamspatzenhirn/rviz_2d_overlay_plugins.git
      version: main

While somewhat intimidating at first, rosdoc2 really is just a very convenient wrapper around the commonly used Sphinx documentation framework including its C++ integration with doxygen via breathe + exhale. It creates a somewhat sensible default configuration for packages with no documentation or configuration at all, applies some options for a uniform theme and integration with other packages.

Custom Sphinx project

But where do we go once the default is not sufficient anymore (which is immediately once you start writing docs which go beyond API-docs)? Luckily, it is possible to setup a completely standard sphinx project, which rosdoc2 will pick up on. Using the sphinx-quickstart tool in the <package-root>/doc directory creates an empty sphinx project that rosdoc2 will find. This does not require any custom rosdoc2.yaml! Now, you can write any free-form documentation, tutorials and more just as you would with sphinx, and build and preview them using:

rosdoc2 build --package-path ./<package-path>

Including the generated (default) pages in the custom project

I wanted to still include the generated API docs in a subdirectory, and link to it from my new, custom index page. Looking at the default index page, all it does is link to generated/index. I added a page cpp_api_docs.rst besides index.rst, with the following content:

C++ API Docs

These are the autogenerated docs for the internal implementation.

.. toctree::
   :maxdepth: 3
   :caption: Contents:

   rviz_2d_overlay_plugins <generated/index>

Which is included from index.rst:

.. toctree::
   :maxdepth: 2
   :caption: Contents:


This results in the generated docs to appear in a sub-category “C++ API Docs” without cluttering the index page or table of contents!

Including an existing README.md

I already had a README.md with a few screenshots, which I wanted to use as the index page for the documentation, without copying it. After some fiddling around with sphinx, I found a satisfying solution which doesn’t require changing the readme to rst and doesn’t break relative paths to images included in the markdown:

First, create a proxy-file readme_include.md next to index.rst. This is a markdown file which just includes the original README.md, but preserves the relative image paths, which would otherwise break in the next step:

```{include} ../README.md

Then, include the contents of this file from index.rst using myst to include markdown from rst:

.. include:: readme_include.md
   :parser: myst_parser.sphinx_

This also requires adding myst_parser to the extensions in conf.py:

extensions = ["myst_parser"]

What now?

I will now try to include this in the README of rosdoc2, i guess…

Up next: finding out how to automate more of the process, such as eliminating options in config.py that could be generated from package.xml and generating docs from ROS message definitions!