From 9dce0bbd5efce68c9cc5c9a879d3b9b069907abd Mon Sep 17 00:00:00 2001 From: R Kent James Date: Fri, 21 Nov 2025 08:13:58 -0800 Subject: [PATCH] Disable TAGFILES in rosdoc2 to separate namespace tf2 documentation into packages Signed-off-by: R Kent James Generated-by: Portions of this commit may include code completion from github.copilot version 1.372.0 or later --- tf2/rosdoc2.yaml | 89 +++++++++++++++++++++------------ tf2/rosdoc2.yaml.ild | 68 +++++++++++++++++++++++++ tf2_bullet/package.xml | 1 + tf2_bullet/rosdoc2.yaml | 91 +++++++++++++++++++++++++++++++++ tf2_eigen/package.xml | 1 + tf2_eigen/rosdoc2.yaml | 91 +++++++++++++++++++++++++++++++++ tf2_eigen_kdl/package.xml | 1 + tf2_eigen_kdl/rosdoc2.yaml | 91 +++++++++++++++++++++++++++++++++ tf2_kdl/package.xml | 1 + tf2_kdl/rosdoc.yaml | 7 --- tf2_kdl/rosdoc2.yaml | 91 +++++++++++++++++++++++++++++++++ tf2_ros/rosdoc2.yaml | 100 +++++++++++++++++++++++++++++++------ tf2_ros_py/rosdoc2.yaml | 92 ++++++++++++++++++++-------------- 13 files changed, 631 insertions(+), 93 deletions(-) create mode 100644 tf2/rosdoc2.yaml.ild create mode 100644 tf2_bullet/rosdoc2.yaml create mode 100644 tf2_eigen/rosdoc2.yaml create mode 100644 tf2_eigen_kdl/rosdoc2.yaml delete mode 100644 tf2_kdl/rosdoc.yaml create mode 100644 tf2_kdl/rosdoc2.yaml diff --git a/tf2/rosdoc2.yaml b/tf2/rosdoc2.yaml index a80c829b8..30aaba186 100644 --- a/tf2/rosdoc2.yaml +++ b/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', '' + # 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' + } diff --git a/tf2/rosdoc2.yaml.ild b/tf2/rosdoc2.yaml.ild new file mode 100644 index 000000000..a80c829b8 --- /dev/null +++ b/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: '' + } diff --git a/tf2_bullet/package.xml b/tf2_bullet/package.xml index 954c00c66..b1197a43b 100644 --- a/tf2_bullet/package.xml +++ b/tf2_bullet/package.xml @@ -32,6 +32,7 @@ ament_cmake + rosdoc2.yaml diff --git a/tf2_bullet/rosdoc2.yaml b/tf2_bullet/rosdoc2.yaml new file mode 100644 index 000000000..14b002e52 --- /dev/null +++ b/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', '' + # 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' + } diff --git a/tf2_eigen/package.xml b/tf2_eigen/package.xml index dde762df7..dad0ce194 100644 --- a/tf2_eigen/package.xml +++ b/tf2_eigen/package.xml @@ -28,5 +28,6 @@ ament_cmake + rosdoc2.yaml diff --git a/tf2_eigen/rosdoc2.yaml b/tf2_eigen/rosdoc2.yaml new file mode 100644 index 000000000..d8986e5f9 --- /dev/null +++ b/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', '' + # 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' + } diff --git a/tf2_eigen_kdl/package.xml b/tf2_eigen_kdl/package.xml index b51e23c94..378174e94 100644 --- a/tf2_eigen_kdl/package.xml +++ b/tf2_eigen_kdl/package.xml @@ -35,5 +35,6 @@ ament_cmake + rosdoc2.yaml diff --git a/tf2_eigen_kdl/rosdoc2.yaml b/tf2_eigen_kdl/rosdoc2.yaml new file mode 100644 index 000000000..4cad32893 --- /dev/null +++ b/tf2_eigen_kdl/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_kdl', + + ## 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_kdl 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', '' + # doxygen_input_dir: null, + } + - sphinx: { + # name: 'tf2_eigen_kdl', + ## 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' + } diff --git a/tf2_kdl/package.xml b/tf2_kdl/package.xml index b2daae8cf..8737e43fd 100644 --- a/tf2_kdl/package.xml +++ b/tf2_kdl/package.xml @@ -36,6 +36,7 @@ ament_cmake + rosdoc2.yaml diff --git a/tf2_kdl/rosdoc.yaml b/tf2_kdl/rosdoc.yaml deleted file mode 100644 index a1d78b9d6..000000000 --- a/tf2_kdl/rosdoc.yaml +++ /dev/null @@ -1,7 +0,0 @@ - - builder: doxygen - name: C++ API - output_dir: c++ - file_patterns: '*.c *.cpp *.h *.cc *.hh *.dox' - - builder: sphinx - name: Python API - output_dir: python diff --git a/tf2_kdl/rosdoc2.yaml b/tf2_kdl/rosdoc2.yaml new file mode 100644 index 000000000..5531b6b93 --- /dev/null +++ b/tf2_kdl/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_kdl', + + ## 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_kdl 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', '' + # doxygen_input_dir: null, + } + - sphinx: { + # name: 'tf2_kdl', + ## 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' + } diff --git a/tf2_ros/rosdoc2.yaml b/tf2_ros/rosdoc2.yaml index f5619c9b2..abfe7a7db 100644 --- a/tf2_ros/rosdoc2.yaml +++ b/tf2_ros/rosdoc2.yaml @@ -1,23 +1,91 @@ +## Default configuration, generated by rosdoc2. + +## This 'attic section' self-documents this file's type and version. type: 'rosdoc2 config' version: 1 --- -settings: - generate_package_index: true - python_source: 'tf2_ros' - always_run_doxygen: false - always_run_sphinx_apidoc: false - enable_breathe: false - enable_exhale: false +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_ros', + + ## 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: - - doxygen: { - name: 'tf2_ros C++ API', - output_dir: 'generated/doxygen', - } - - sphinx: { - name: 'tf2_ros Python API', - doxygen_xml_directory: 'generated/doxygen/xml', - output_dir: '' - } + ## 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_ros 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', '' + # doxygen_input_dir: null, + } + - sphinx: { + # name: 'tf2_ros', + ## 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' + } diff --git a/tf2_ros_py/rosdoc2.yaml b/tf2_ros_py/rosdoc2.yaml index 4cc5e3ff5..423c3b2c5 100644 --- a/tf2_ros_py/rosdoc2.yaml +++ b/tf2_ros_py/rosdoc2.yaml @@ -1,73 +1,91 @@ +## 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 - +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_ros' + python_source: 'tf2_ros', ## 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: true + # 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 True, will ensure breathe is part of the 'extensions', - # and will set all of the breathe configurations, if not set, and override - # settings as needed if they are set by this configuration. - enable_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 ensure exhale is part of the 'extensions', - # and will set all of the exhale configurations, if not set, and override - # settings as needed if they are set by this configuration. - enable_exhale: false + ## 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. - ## 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_ros Public C/C++ API', - output_dir: 'generated/doxygen' - } + # name: 'tf2_ros_py 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: [], + ## location of include files for Doxygen. By default, rosdoc2 searches in + ## 'include', 'src', '' + # doxygen_input_dir: null, + } - sphinx: { - name: 'tf2_ros', + # name: 'tf2_ros_py', ## This path is relative to output staging. # doxygen_xml_directory: 'generated/doxygen/xml', - sphinx_sourcedir: 'doc/source/', - output_dir: '' - } + # 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' + }