Add show_exec_dep to rosdoc2.yaml, avoid 'meta' name

rosdoc2/verbs/build/builders/index.rst.jinja

@@ -21,13 +21,14 @@
 {% if interface_counts['srv'] > 0 %}   Service Definitions <interfaces/service_definitions>{% endif %}
 {% if interface_counts['action'] > 0 %}   Action Definitions <interfaces/action_definitions>{% endif %}
 {% if has_standard_docs %}   Standard Documents <standards>{% endif %}
-{% if is_meta %}
-Dependencies of this META package
----------------------------------
-{% for dependency in package.exec_depends %}
+{% if show_exec_dep %}
+
+Execution Dependencies of this package
+--------------------------------------
+{% for dependency in package.exec_depends -%}
 * `{{ dependency }} <{{ base_url }}/{{ dependency }}>`_
-{% endfor %}
-{% endif %}
+{% endfor -%}
+{% endif -%}
 
 {% if has_documentation %}
 .. toctree::

rosdoc2/verbs/build/builders/sphinx_builder.py

@@ -474,19 +474,29 @@ def build(self, *, doc_build_folder, output_staging_directory):
         has_cpp = build_context.build_type in ['ament_cmake', 'cmake'] or always_run_doxygen
         package = self.build_context.package
 
-        # Detect meta packages. They have no build_dependencies, do have exec_dependencies,
-        # and have no subdirectories except for possibly 'doc'.
-        is_meta = True
-        if package.build_depends or not package.exec_depends:
-            is_meta = False
+        show_exec_dep = build_context.show_exec_dep
+        if show_exec_dep is None:
+            if package.is_metapackage():
+                show_exec_dep = True
+                logger.info('show_exec_dep set True because is_metapackage set in package.xml')
+            # Detect meta packages. They have no build_dependencies, do have exec_dependencies,
+            # and have no subdirectories except for possibly 'doc'.
+            elif package.build_depends or not package.exec_depends:
+                show_exec_dep = False
+                logger.info("show_exec_dep set False because depends don't match meta pattern")
+            else:
+                pp = Path(package_xml_directory)
+                subdirectories = [x for x in pp.iterdir() if x.is_dir()]
+                for subdirectory in subdirectories:
+                    if subdirectory.name != 'doc':
+                        show_exec_dep = False
+                        logger.info('show_exec_dep set False because non-"doc/" directory found')
+                        continue
+            if show_exec_dep is None:
+                show_exec_dep = True
+                logger.info('show_exec_dep set True as package matches meta pattern')
         else:
-            pp = Path(package_xml_directory)
-            subdirectories = [x for x in pp.iterdir() if x.is_dir()]
-            for subdirectory in subdirectories:
-                if subdirectory.name != 'doc':
-                    is_meta = False
-                    continue
-
+            logger.info(f'show_exec_dep set to {show_exec_dep} in rosdoc2.yml')
         self.template_variables.update({
             'has_python': has_python,
             'has_cpp': has_cpp,
@@ -496,7 +506,7 @@ def build(self, *, doc_build_folder, output_staging_directory):
             'interface_counts': interface_counts,
             'package': package,
             'base_url': base_url,
-            'is_meta': is_meta or package.is_metapackage(),
+            'show_exec_dep': show_exec_dep,
         })
 
         # Setup rosdoc2 Sphinx file which will include and extend the one in

rosdoc2/verbs/build/inspect_package_for_settings.py

@@ -66,6 +66,14 @@
     # for documentation purposes only. If not provided, documentation will be
     # generated assuming the build_type in package.xml.
     # override_build_type: 'ament_python'
+
+    # This boolean setting, if provided, determines whether the external dependencies of a package
+    # are shown in the home page of the documentation, which is useful for packages that are only
+    # used to force loading of other packages (which are sometimes called meta packages).
+    # If not set, then the decision to show the external dependencies is made on the following
+    # heuristics: show if the package has no build_depend, does have exec_depend, and has no
+    # subdirectories except an optional doc/ subdirectory.
+    # show_exec_dep: None
 builders:
     ## Each stanza represents a separate build step, performed by a specific 'builder'.
     ## The key of each stanza is the builder to use; this must be one of the

rosdoc2/verbs/build/parse_rosdoc2_yaml.py

@@ -61,6 +61,7 @@ def parse_rosdoc2_yaml(yaml_string, build_context):
     build_context.always_run_doxygen = settings_dict.get('always_run_doxygen', False)
     build_context.always_run_sphinx_apidoc = settings_dict.get('always_run_sphinx_apidoc', False)
     build_context.build_type = settings_dict.get('override_build_type', build_context.build_type)
+    build_context.show_exec_dep = settings_dict.get('show_exec_dep', None)
 
     if 'builders' not in config:
         raise ValueError(

test/packages/do_show_dep/package.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>do_show_dep</name>
+  <version>0.1.2</version>
+  <description>forcing show of exec dependencies</description>
+  <maintainer email="[email protected]">Some One</maintainer>
+  <license>Apache License 2.0</license>
+  <depend>basic_cpp</depend>
+  <exec_depend>full_package</exec_depend>
+  <exec_depend>minimum_package</exec_depend>
+  <exec_depend>only_messages</exec_depend>
+  <exec_depend>only_python</exec_depend>
+  <export>
+    <rosdoc2>rosdoc2.yaml</rosdoc2>
+  </export>
+</package>

test/packages/do_show_dep/rosdoc2.yaml

@@ -0,0 +1,70 @@
+## Default configuration, generated by rosdoc2.
+
+## This 'attic section' self-documents this file's type and version.
+type: 'rosdoc2 config'
+version: 1
+
+---
+
+settings:
+    ## If this is true, a standard index page is generated in the output directory.
+    ## It uses the package information from the 'package.xml' to show details
+    ## about the package, creates a table of contents for the various builders
+    ## that were run, and may contain links to things like build farm jobs for
+    ## this package or links to other versions of this package.
+
+    ## If false, you can still include content that would have been in the index
+    ## into one of your '.rst' files from your Sphinx project, using the
+    ## '.. include::' directive in Sphinx.
+    ## For example, you could include it in a custom 'index.rst' so you can have
+    ## the standard information followed by custom content.
+
+    ## TODO(wjwwood): provide a concrete example of this (relative path?)
+
+    ## If this is not specified explicitly, it defaults to 'true'.
+    generate_package_index: true
+
+    ## This setting, if true, attempts to run `doxygen` and the `breathe`/`exhale`
+    ## extensions to `sphinx` regardless of build type. This is most useful if the
+    ## user would like to generate C/C++ API documentation for a package that is not
+    ## of the `ament_cmake/cmake` build type.
+    always_run_doxygen: false
+
+    ## This setting, if true, attempts to run `sphinx-apidoc` regardless of build
+    ## type. This is most useful if the user would like to generate Python API
+    ## documentation for a package that is not of the `ament_python` build type.
+    always_run_sphinx_apidoc: false
+
+    # This setting, if provided, will override the build_type of this package
+    # for documentation purposes only. If not provided, documentation will be
+    # generated assuming the build_type in package.xml.
+    # override_build_type: 'ament_python'
+
+    # This boolean setting, if provided, determines whether the external dependencies of a package
+    # are shown in the home page of the documentation, which is useful for packages that are only
+    # used to force loading of other packages (which are sometimes called meta packages).
+    # If not set, then the decision to show the external dependencies is made on the following
+    # heuristics: show if the package has no build_depend, does have exec_depend, and has no
+    # subdirectories except an optional doc/ subdirectory.
+    show_exec_dep: true
+builders:
+    ## Each stanza represents a separate build step, performed by a specific 'builder'.
+    ## The key of each stanza is the builder to use; this must be one of the
+    ## available builders.
+    ## The value of each stanza is a dictionary of settings for the builder that
+    ## outputs to that directory.
+    ## Required keys in the settings dictionary are:
+    ##  * 'output_dir' - determines output subdirectory for builder instance
+    ##                   relative to --output-directory
+    ##  * 'name' - used when referencing the built docs from the index.
+
+    - doxygen: {
+        name: 'forcing show of exec dependecies',
+        output_dir: 'generated/doxygen'
+    }
+    - sphinx: {
+        name: 'do_show_dep',
+        ## This path is relative to output staging.
+        doxygen_xml_directory: 'generated/doxygen/xml',
+        output_dir: ''
+    }

test/packages/dont_show_dep/package.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>dont_show_dep</name>
+  <version>0.1.2</version>
+  <description>explicitly not showing dependencies</description>
+  <maintainer email="[email protected]">Some One</maintainer>
+  <license>Apache License 2.0</license>
+  <exec_depend>basic_cpp</exec_depend>
+  <exec_depend>full_package</exec_depend>
+  <exec_depend>minimum_package</exec_depend>
+  <exec_depend>only_messages</exec_depend>
+  <exec_depend>only_python</exec_depend>
+  <export>
+    <rosdoc2>rosdoc2.yaml</rosdoc2>
+  </export>
+</package>

test/packages/dont_show_dep/rosdoc2.yaml

@@ -0,0 +1,70 @@
+## Default configuration, generated by rosdoc2.
+
+## This 'attic section' self-documents this file's type and version.
+type: 'rosdoc2 config'
+version: 1
+
+---
+
+settings:
+    ## If this is true, a standard index page is generated in the output directory.
+    ## It uses the package information from the 'package.xml' to show details
+    ## about the package, creates a table of contents for the various builders
+    ## that were run, and may contain links to things like build farm jobs for
+    ## this package or links to other versions of this package.
+
+    ## If false, you can still include content that would have been in the index
+    ## into one of your '.rst' files from your Sphinx project, using the
+    ## '.. include::' directive in Sphinx.
+    ## For example, you could include it in a custom 'index.rst' so you can have
+    ## the standard information followed by custom content.
+
+    ## TODO(wjwwood): provide a concrete example of this (relative path?)
+
+    ## If this is not specified explicitly, it defaults to 'true'.
+    generate_package_index: true
+
+    ## This setting, if true, attempts to run `doxygen` and the `breathe`/`exhale`
+    ## extensions to `sphinx` regardless of build type. This is most useful if the
+    ## user would like to generate C/C++ API documentation for a package that is not
+    ## of the `ament_cmake/cmake` build type.
+    always_run_doxygen: false
+
+    ## This setting, if true, attempts to run `sphinx-apidoc` regardless of build
+    ## type. This is most useful if the user would like to generate Python API
+    ## documentation for a package that is not of the `ament_python` build type.
+    always_run_sphinx_apidoc: false
+
+    # This setting, if provided, will override the build_type of this package
+    # for documentation purposes only. If not provided, documentation will be
+    # generated assuming the build_type in package.xml.
+    # override_build_type: 'ament_python'
+
+    # This boolean setting, if provided, determines whether the external dependencies of a package
+    # are shown in the home page of the documentation, which is useful for packages that are only
+    # used to force loading of other packages (which are sometimes called meta packages).
+    # If not set, then the decision to show the external dependencies is made on the following
+    # heuristics: show if the package has no build_depend, does have exec_depend, and has no
+    # subdirectories except an optional doc/ subdirectory.
+    show_exec_dep: false
+builders:
+    ## Each stanza represents a separate build step, performed by a specific 'builder'.
+    ## The key of each stanza is the builder to use; this must be one of the
+    ## available builders.
+    ## The value of each stanza is a dictionary of settings for the builder that
+    ## outputs to that directory.
+    ## Required keys in the settings dictionary are:
+    ##  * 'output_dir' - determines output subdirectory for builder instance
+    ##                   relative to --output-directory
+    ##  * 'name' - used when referencing the built docs from the index.
+
+    - doxygen: {
+        name: 'explicitly not showing dependencies',
+        output_dir: 'generated/doxygen'
+    }
+    - sphinx: {
+        name: 'dont_show_dep',
+        ## This path is relative to output staging.
+        doxygen_xml_directory: 'generated/doxygen/xml',
+        output_dir: ''
+    }

test/test_builder.py

@@ -184,8 +184,8 @@ def test_minimum_package(session_dir):
     ]
     excludes = [
         'classes and structs',  # only found in C++ projects
-        'dependencies of this meta package',  # only in meta packages
-        'links',  # only found if urls defined
+        'links',  # only found if urls defined,
+        'execution dependencies of this package',  # only in meta packages
     ]
     file_includes = [
         'search.html',
@@ -307,7 +307,31 @@ def test_meta_package(session_dir):
     do_build_package(DATAPATH / PKG_NAME, session_dir)
 
     includes = [
-        'dependencies of this meta package',
+        'execution dependencies of this package',
         'only_python',
     ]
     do_test_package(PKG_NAME, session_dir, includes=includes)
+
+
+def test_do_show_dep(session_dir):
+    """Tests rosdoc2.yaml with show_exec_dep=true."""
+    PKG_NAME = 'do_show_dep'
+
+    do_build_package(DATAPATH / PKG_NAME, session_dir)
+
+    includes = [
+        'execution dependencies of this package',
+    ]
+    do_test_package(PKG_NAME, session_dir, includes=includes)
+
+
+def test_dont_show_dep(session_dir):
+    """Tests rosdoc2.yaml with show_exec_dep=false."""
+    PKG_NAME = 'dont_show_dep'
+
+    do_build_package(DATAPATH / PKG_NAME, session_dir)
+
+    excludes = [
+        'execution dependencies of this package',
+    ]
+    do_test_package(PKG_NAME, session_dir, excludes=excludes)