Disable TAGFILES in rosdoc2 to separate namespace tf2 documentation in packages

tf2/rosdoc2.yaml

@@ -6,63 +6,86 @@ 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
-
+settings: {
     ## This setting is relevant mostly if the standard Python package layout cannot
     ## be assumed for 'sphinx-apidoc' invocation. The user can provide the path
     ## (relative to the 'package.xml' file) where the Python modules defined by this
     ## package are located.
-    python_source: 'tf2'
+    # python_source: 'tf2',
 
     ## 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
+    # always_run_doxygen: false,
+
+    ## This setting, if true, will skip running doxygen` and the `breathe`/`exhale`
+    ## extensions to `sphinx` regardless of build type. This is most useful if the
+    ## user has generated C++ documentation elsewhere that is included in the doc
+    ## folder, or in external documentation.
+    # never_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
+    # always_run_sphinx_apidoc: false,
+
+    ## This setting, if true, will skip running `sphinx-apidoc` regardless of build
+    ## type. This is most useful if the user has generated python documentation elsewhere
+    ## that is included in the doc folder, or in external documentation.
+    # never_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_cmake',
+
+    ## This setting, if true, will skip using breathe to process the C++ documentation, and
+    #  use the doxygen html instead. This is intended for cases where breathe is throwing
+    #  errors.
+    # disable_breathe: 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 setting, if true, will display a link to the Doxygen html output.
+    # show_doxygen_html: 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:
+    ## Keys in all 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: 'tf2 Public C/C++ API',
-        output_dir: 'generated/doxygen'
-    }
+        # name: 'tf2 Public C/C++ API',
+        # output_dir: 'generated/doxygen',
+        ## file name for a user-supplied Doxyfile
+        # doxyfile: null,
+        ## additional statements to add to the Doxyfile, list of strings
+        extra_doxyfile_statements: ['TAGFILES = ""'],
+        ## location of include files for Doxygen. By default, rosdoc2 searches in
+        ## 'include', 'src', '<package.name>'
+        # doxygen_input_dir: null,
+      }
     - sphinx: {
-        name: 'tf2',
+        # name: 'tf2',
         ## This path is relative to output staging.
-        doxygen_xml_directory: 'generated/doxygen/xml',
-        output_dir: ''
-    }
+        # doxygen_xml_directory: 'generated/doxygen/xml',
+        # output_dir: '',
+        ## If sphinx_sourcedir is specified and not null, then the documentation in that folder
+        ## (specified relative to the package.xml directory) will replace rosdoc2's normal output.
+        ## If sphinx_sourcedir is left unspecified, any documentation found in the doc/ or
+        ## doc/source/ folder will still be included by default, along with other relevant package
+        ## information.
+        # sphinx_sourcedir: null,
+        ## Directory (relative to the package.xml directory) where user documentation is found. If
+        ## documentation is in one of the standard locations (doc/ or doc/source) this is not
+        ## needed. Unlike sphinx_sourcedir, specifying this does not override the standard rosdoc2
+        ## output, but includes this user documentation along with other items included by default
+        ## by rosdoc2.
+        ## If the value is null, any found documentation in doc/ or doc/source/ is ignored.
+        # user_doc_dir: 'doc'
+      }

tf2/rosdoc2.yaml.ild

@@ -0,0 +1,68 @@
+## 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 is relevant mostly if the standard Python package layout cannot
+    ## be assumed for 'sphinx-apidoc' invocation. The user can provide the path
+    ## (relative to the 'package.xml' file) where the Python modules defined by this
+    ## package are located.
+    python_source: 'tf2'
+
+    ## 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'
+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: 'tf2 Public C/C++ API',
+        output_dir: 'generated/doxygen'
+    }
+    - sphinx: {
+        name: 'tf2',
+        ## This path is relative to output staging.
+        doxygen_xml_directory: 'generated/doxygen/xml',
+        output_dir: ''
+    }

tf2_bullet/package.xml

@@ -32,6 +32,7 @@
 
   <export>
     <build_type>ament_cmake</build_type>
+    <rosdoc2>rosdoc2.yaml</rosdoc2>
   </export>
 
 </package>

tf2_bullet/rosdoc2.yaml

@@ -0,0 +1,91 @@
+## Default configuration, generated by rosdoc2.
+
+## This 'attic section' self-documents this file's type and version.
+type: 'rosdoc2 config'
+version: 1
+
+---
+
+settings: {
+    ## This setting is relevant mostly if the standard Python package layout cannot
+    ## be assumed for 'sphinx-apidoc' invocation. The user can provide the path
+    ## (relative to the 'package.xml' file) where the Python modules defined by this
+    ## package are located.
+    # python_source: 'tf2_bullet',
+
+    ## 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, will skip running doxygen` and the `breathe`/`exhale`
+    ## extensions to `sphinx` regardless of build type. This is most useful if the
+    ## user has generated C++ documentation elsewhere that is included in the doc
+    ## folder, or in external documentation.
+    # never_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 true, will skip running `sphinx-apidoc` regardless of build
+    ## type. This is most useful if the user has generated python documentation elsewhere
+    ## that is included in the doc folder, or in external documentation.
+    # never_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_cmake',
+
+    ## This setting, if true, will skip using breathe to process the C++ documentation, and
+    #  use the doxygen html instead. This is intended for cases where breathe is throwing
+    #  errors.
+    # disable_breathe: false,
+
+    ## This setting, if true, will display a link to the Doxygen html output.
+    # show_doxygen_html: 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.
+    ## Keys in all 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: 'tf2_bullet Public C/C++ API',
+        # output_dir: 'generated/doxygen',
+        ## file name for a user-supplied Doxyfile
+        # doxyfile: null,
+        ## additional statements to add to the Doxyfile, list of strings
+        extra_doxyfile_statements: ['TAGFILES = ""'],
+        ## location of include files for Doxygen. By default, rosdoc2 searches in
+        ## 'include', 'src', '<package.name>'
+        # doxygen_input_dir: null,
+      }
+    - sphinx: {
+        # name: 'tf2_bullet',
+        ## This path is relative to output staging.
+        # doxygen_xml_directory: 'generated/doxygen/xml',
+        # output_dir: '',
+        ## If sphinx_sourcedir is specified and not null, then the documentation in that folder
+        ## (specified relative to the package.xml directory) will replace rosdoc2's normal output.
+        ## If sphinx_sourcedir is left unspecified, any documentation found in the doc/ or
+        ## doc/source/ folder will still be included by default, along with other relevant package
+        ## information.
+        # sphinx_sourcedir: null,
+        ## Directory (relative to the package.xml directory) where user documentation is found. If
+        ## documentation is in one of the standard locations (doc/ or doc/source) this is not
+        ## needed. Unlike sphinx_sourcedir, specifying this does not override the standard rosdoc2
+        ## output, but includes this user documentation along with other items included by default
+        ## by rosdoc2.
+        ## If the value is null, any found documentation in doc/ or doc/source/ is ignored.
+        # user_doc_dir: 'doc'
+      }

tf2_eigen/package.xml

@@ -28,5 +28,6 @@
 
   <export>
     <build_type>ament_cmake</build_type>
+    <rosdoc2>rosdoc2.yaml</rosdoc2>
   </export>
 </package>

tf2_eigen/rosdoc2.yaml

@@ -0,0 +1,91 @@
+## Default configuration, generated by rosdoc2.
+
+## This 'attic section' self-documents this file's type and version.
+type: 'rosdoc2 config'
+version: 1
+
+---
+
+settings: {
+    ## This setting is relevant mostly if the standard Python package layout cannot
+    ## be assumed for 'sphinx-apidoc' invocation. The user can provide the path
+    ## (relative to the 'package.xml' file) where the Python modules defined by this
+    ## package are located.
+    # python_source: 'tf2_eigen',
+
+    ## 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, will skip running doxygen` and the `breathe`/`exhale`
+    ## extensions to `sphinx` regardless of build type. This is most useful if the
+    ## user has generated C++ documentation elsewhere that is included in the doc
+    ## folder, or in external documentation.
+    # never_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 true, will skip running `sphinx-apidoc` regardless of build
+    ## type. This is most useful if the user has generated python documentation elsewhere
+    ## that is included in the doc folder, or in external documentation.
+    # never_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_cmake',
+
+    ## This setting, if true, will skip using breathe to process the C++ documentation, and
+    #  use the doxygen html instead. This is intended for cases where breathe is throwing
+    #  errors.
+    # disable_breathe: false,
+
+    ## This setting, if true, will display a link to the Doxygen html output.
+    # show_doxygen_html: 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.
+    ## Keys in all 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: 'tf2_eigen Public C/C++ API',
+        # output_dir: 'generated/doxygen',
+        ## file name for a user-supplied Doxyfile
+        # doxyfile: null,
+        ## additional statements to add to the Doxyfile, list of strings
+        extra_doxyfile_statements: ['TAGFILES = ""'],
+        ## location of include files for Doxygen. By default, rosdoc2 searches in
+        ## 'include', 'src', '<package.name>'
+        # doxygen_input_dir: null,
+      }
+    - sphinx: {
+        # name: 'tf2_eigen',
+        ## This path is relative to output staging.
+        # doxygen_xml_directory: 'generated/doxygen/xml',
+        # output_dir: '',
+        ## If sphinx_sourcedir is specified and not null, then the documentation in that folder
+        ## (specified relative to the package.xml directory) will replace rosdoc2's normal output.
+        ## If sphinx_sourcedir is left unspecified, any documentation found in the doc/ or
+        ## doc/source/ folder will still be included by default, along with other relevant package
+        ## information.
+        # sphinx_sourcedir: null,
+        ## Directory (relative to the package.xml directory) where user documentation is found. If
+        ## documentation is in one of the standard locations (doc/ or doc/source) this is not
+        ## needed. Unlike sphinx_sourcedir, specifying this does not override the standard rosdoc2
+        ## output, but includes this user documentation along with other items included by default
+        ## by rosdoc2.
+        ## If the value is null, any found documentation in doc/ or doc/source/ is ignored.
+        # user_doc_dir: 'doc'
+      }

tf2_eigen_kdl/package.xml

@@ -35,5 +35,6 @@
 
   <export>
     <build_type>ament_cmake</build_type>
+    <rosdoc2>rosdoc2.yaml</rosdoc2>
   </export>
 </package>