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