rosdoc2

Documentation for ROS 2 packages can be built with rosdoc2.

When a doc job is configured in the rosdistro, the resulting documentation is uploaded to docs.ros.org. The design document for per package documentation lays out the directory structure.

Linking to Other Packages

This is a dirty hack, but appears to be the only way to have the table of contents link to another package's documentation without hard-coding the distro. The trailing http:// changes how Sphinx processes the link:

.. toctree::
   :maxdepth: 2

   other_package <../other_package/index.html#http://>

An example of this can be seen in the documentation for image_pipeline, where we want to link to the documentation for each of the packages within the metapackage.

Documenting Metapackages

A metapackage is one that contains no code and exists basically to bundle up a set of dependencies. For instance image_pipeline is a repository containing several packages for image processing - and the image_pipeline metapackage depends on every package in the repository to make it easier to install with apt install ros-<distro>-image-pipeline rather than specifying each package individually. This does lead to an issue with rosdoc2, which will fail if there is no code to document. If you want to add tutorials or documentation to a metapackage, you need to use a rosdoc2.yaml file to properly build your documentation (which we assume is located in the doc folder:

type: 'rosdoc2 config'
version: 1

---

settings:
    # Not generating any documentation of code
    generate_package_index: false
    always_run_doxygen: false
    enable_breathe: false
    enable_exhale: false
    always_run_sphinx_apidoc: false
    # Lie to rosdoc2, claim to be a python package
    override_build_type: 'ament_python'
    # Lie to rosdoc2 again, say your source is in doc folder
    python_source: 'doc'

builders:
   # Configure Sphinx with the location of the docs:
    - sphinx: {
        name: 'image_pipeline',
        sphinx_sourcedir: 'doc',
        output_dir: ''
    }

Don't forget to add your yaml file to the package.xml:

<export>
  <rosdoc2>rosdoc2.yaml</rosdoc2>
</export>