how to document metapackages

pages/rosdoc2.md

@@ -11,7 +11,6 @@ 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:
@@ -26,3 +25,50 @@ link to another package's documentation without hard-coding the distro. The trai
 An example of this can be seen in the documentation for
 [image_pipeline](http://docs.ros.org/en/rolling/p/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:
+
+```yaml
+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``:
+
+```xml
+<export>
+ <rosdoc2>rosdoc2.yaml</rosdoc2>
+</export>
+```