Skip to content

Commit 1322e89

Browse files
rkentrkent
authored
Disable TAGFILES in rosdoc2 to separate namespace tf2 documentation into packages (#856)
Generated-by: Portions of this commit may include code completion from github.copilot version 1.372.0 or later Signed-off-by: R Kent James <[email protected]>
1 parent 5e6fd95 commit 1322e89

File tree

13 files changed

+631
-93
lines changed

13 files changed

+631
-93
lines changed

‎tf2/rosdoc2.yaml‎

Lines changed: 56 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -6,63 +6,86 @@ version: 1
66

77
---
88

9-
settings:
10-
## If this is true, a standard index page is generated in the output directory.
11-
## It uses the package information from the 'package.xml' to show details
12-
## about the package, creates a table of contents for the various builders
13-
## that were run, and may contain links to things like build farm jobs for
14-
## this package or links to other versions of this package.
15-
16-
## If false, you can still include content that would have been in the index
17-
## into one of your '.rst' files from your Sphinx project, using the
18-
## '.. include::' directive in Sphinx.
19-
## For example, you could include it in a custom 'index.rst' so you can have
20-
## the standard information followed by custom content.
21-
22-
## TODO(wjwwood): provide a concrete example of this (relative path?)
23-
24-
## If this is not specified explicitly, it defaults to 'true'.
25-
generate_package_index: true
26-
9+
settings: {
2710
## This setting is relevant mostly if the standard Python package layout cannot
2811
## be assumed for 'sphinx-apidoc' invocation. The user can provide the path
2912
## (relative to the 'package.xml' file) where the Python modules defined by this
3013
## package are located.
31-
python_source: 'tf2'
14+
# python_source: 'tf2',
3215

3316
## This setting, if true, attempts to run `doxygen` and the `breathe`/`exhale`
3417
## extensions to `sphinx` regardless of build type. This is most useful if the
3518
## user would like to generate C/C++ API documentation for a package that is not
3619
## of the `ament_cmake/cmake` build type.
37-
always_run_doxygen: false
20+
# always_run_doxygen: false,
21+
22+
## This setting, if true, will skip running doxygen` and the `breathe`/`exhale`
23+
## extensions to `sphinx` regardless of build type. This is most useful if the
24+
## user has generated C++ documentation elsewhere that is included in the doc
25+
## folder, or in external documentation.
26+
# never_run_doxygen: false,
3827

3928
## This setting, if true, attempts to run `sphinx-apidoc` regardless of build
4029
## type. This is most useful if the user would like to generate Python API
4130
## documentation for a package that is not of the `ament_python` build type.
42-
always_run_sphinx_apidoc: false
31+
# always_run_sphinx_apidoc: false,
32+
33+
## This setting, if true, will skip running `sphinx-apidoc` regardless of build
34+
## type. This is most useful if the user has generated python documentation elsewhere
35+
## that is included in the doc folder, or in external documentation.
36+
# never_run_sphinx_apidoc: false,
37+
38+
## This setting, if provided, will override the build_type of this package
39+
## for documentation purposes only. If not provided, documentation will be
40+
## generated assuming the build_type in package.xml.
41+
# override_build_type: 'ament_cmake',
42+
43+
## This setting, if true, will skip using breathe to process the C++ documentation, and
44+
# use the doxygen html instead. This is intended for cases where breathe is throwing
45+
# errors.
46+
# disable_breathe: false,
4347

44-
# This setting, if provided, will override the build_type of this package
45-
# for documentation purposes only. If not provided, documentation will be
46-
# generated assuming the build_type in package.xml.
47-
# override_build_type: 'ament_python'
48+
## This setting, if true, will display a link to the Doxygen html output.
49+
# show_doxygen_html: false,
50+
}
4851
builders:
4952
## Each stanza represents a separate build step, performed by a specific 'builder'.
5053
## The key of each stanza is the builder to use; this must be one of the
5154
## available builders.
5255
## The value of each stanza is a dictionary of settings for the builder that
5356
## outputs to that directory.
54-
## Required keys in the settings dictionary are:
57+
## Keys in all settings dictionary are:
5558
## * 'output_dir' - determines output subdirectory for builder instance
5659
## relative to --output-directory
5760
## * 'name' - used when referencing the built docs from the index.
5861

5962
- doxygen: {
60-
name: 'tf2 Public C/C++ API',
61-
output_dir: 'generated/doxygen'
62-
}
63+
# name: 'tf2 Public C/C++ API',
64+
# output_dir: 'generated/doxygen',
65+
## file name for a user-supplied Doxyfile
66+
# doxyfile: null,
67+
## additional statements to add to the Doxyfile, list of strings
68+
extra_doxyfile_statements: ['TAGFILES = ""'],
69+
## location of include files for Doxygen. By default, rosdoc2 searches in
70+
## 'include', 'src', '<package.name>'
71+
# doxygen_input_dir: null,
72+
}
6373
- sphinx: {
64-
name: 'tf2',
74+
# name: 'tf2',
6575
## This path is relative to output staging.
66-
doxygen_xml_directory: 'generated/doxygen/xml',
67-
output_dir: ''
68-
}
76+
# doxygen_xml_directory: 'generated/doxygen/xml',
77+
# output_dir: '',
78+
## If sphinx_sourcedir is specified and not null, then the documentation in that folder
79+
## (specified relative to the package.xml directory) will replace rosdoc2's normal output.
80+
## If sphinx_sourcedir is left unspecified, any documentation found in the doc/ or
81+
## doc/source/ folder will still be included by default, along with other relevant package
82+
## information.
83+
# sphinx_sourcedir: null,
84+
## Directory (relative to the package.xml directory) where user documentation is found. If
85+
## documentation is in one of the standard locations (doc/ or doc/source) this is not
86+
## needed. Unlike sphinx_sourcedir, specifying this does not override the standard rosdoc2
87+
## output, but includes this user documentation along with other items included by default
88+
## by rosdoc2.
89+
## If the value is null, any found documentation in doc/ or doc/source/ is ignored.
90+
# user_doc_dir: 'doc'
91+
}

‎tf2/rosdoc2.yaml.ild‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
## Default configuration, generated by rosdoc2.
2+
3+
## This 'attic section' self-documents this file's type and version.
4+
type: 'rosdoc2 config'
5+
version: 1
6+
7+
---
8+
9+
settings:
10+
## If this is true, a standard index page is generated in the output directory.
11+
## It uses the package information from the 'package.xml' to show details
12+
## about the package, creates a table of contents for the various builders
13+
## that were run, and may contain links to things like build farm jobs for
14+
## this package or links to other versions of this package.
15+
16+
## If false, you can still include content that would have been in the index
17+
## into one of your '.rst' files from your Sphinx project, using the
18+
## '.. include::' directive in Sphinx.
19+
## For example, you could include it in a custom 'index.rst' so you can have
20+
## the standard information followed by custom content.
21+
22+
## TODO(wjwwood): provide a concrete example of this (relative path?)
23+
24+
## If this is not specified explicitly, it defaults to 'true'.
25+
generate_package_index: true
26+
27+
## This setting is relevant mostly if the standard Python package layout cannot
28+
## be assumed for 'sphinx-apidoc' invocation. The user can provide the path
29+
## (relative to the 'package.xml' file) where the Python modules defined by this
30+
## package are located.
31+
python_source: 'tf2'
32+
33+
## This setting, if true, attempts to run `doxygen` and the `breathe`/`exhale`
34+
## extensions to `sphinx` regardless of build type. This is most useful if the
35+
## user would like to generate C/C++ API documentation for a package that is not
36+
## of the `ament_cmake/cmake` build type.
37+
always_run_doxygen: false
38+
39+
## This setting, if true, attempts to run `sphinx-apidoc` regardless of build
40+
## type. This is most useful if the user would like to generate Python API
41+
## documentation for a package that is not of the `ament_python` build type.
42+
always_run_sphinx_apidoc: false
43+
44+
# This setting, if provided, will override the build_type of this package
45+
# for documentation purposes only. If not provided, documentation will be
46+
# generated assuming the build_type in package.xml.
47+
# override_build_type: 'ament_python'
48+
builders:
49+
## Each stanza represents a separate build step, performed by a specific 'builder'.
50+
## The key of each stanza is the builder to use; this must be one of the
51+
## available builders.
52+
## The value of each stanza is a dictionary of settings for the builder that
53+
## outputs to that directory.
54+
## Required keys in the settings dictionary are:
55+
## * 'output_dir' - determines output subdirectory for builder instance
56+
## relative to --output-directory
57+
## * 'name' - used when referencing the built docs from the index.
58+
59+
- doxygen: {
60+
name: 'tf2 Public C/C++ API',
61+
output_dir: 'generated/doxygen'
62+
}
63+
- sphinx: {
64+
name: 'tf2',
65+
## This path is relative to output staging.
66+
doxygen_xml_directory: 'generated/doxygen/xml',
67+
output_dir: ''
68+
}

‎tf2_bullet/package.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232

3333
<export>
3434
<build_type>ament_cmake</build_type>
35+
<rosdoc2>rosdoc2.yaml</rosdoc2>
3536
</export>
3637

3738
</package>

‎tf2_bullet/rosdoc2.yaml‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
## Default configuration, generated by rosdoc2.
2+
3+
## This 'attic section' self-documents this file's type and version.
4+
type: 'rosdoc2 config'
5+
version: 1
6+
7+
---
8+
9+
settings: {
10+
## This setting is relevant mostly if the standard Python package layout cannot
11+
## be assumed for 'sphinx-apidoc' invocation. The user can provide the path
12+
## (relative to the 'package.xml' file) where the Python modules defined by this
13+
## package are located.
14+
# python_source: 'tf2_bullet',
15+
16+
## This setting, if true, attempts to run `doxygen` and the `breathe`/`exhale`
17+
## extensions to `sphinx` regardless of build type. This is most useful if the
18+
## user would like to generate C/C++ API documentation for a package that is not
19+
## of the `ament_cmake/cmake` build type.
20+
# always_run_doxygen: false,
21+
22+
## This setting, if true, will skip running doxygen` and the `breathe`/`exhale`
23+
## extensions to `sphinx` regardless of build type. This is most useful if the
24+
## user has generated C++ documentation elsewhere that is included in the doc
25+
## folder, or in external documentation.
26+
# never_run_doxygen: false,
27+
28+
## This setting, if true, attempts to run `sphinx-apidoc` regardless of build
29+
## type. This is most useful if the user would like to generate Python API
30+
## documentation for a package that is not of the `ament_python` build type.
31+
# always_run_sphinx_apidoc: false,
32+
33+
## This setting, if true, will skip running `sphinx-apidoc` regardless of build
34+
## type. This is most useful if the user has generated python documentation elsewhere
35+
## that is included in the doc folder, or in external documentation.
36+
# never_run_sphinx_apidoc: false,
37+
38+
## This setting, if provided, will override the build_type of this package
39+
## for documentation purposes only. If not provided, documentation will be
40+
## generated assuming the build_type in package.xml.
41+
# override_build_type: 'ament_cmake',
42+
43+
## This setting, if true, will skip using breathe to process the C++ documentation, and
44+
# use the doxygen html instead. This is intended for cases where breathe is throwing
45+
# errors.
46+
# disable_breathe: false,
47+
48+
## This setting, if true, will display a link to the Doxygen html output.
49+
# show_doxygen_html: false,
50+
}
51+
builders:
52+
## Each stanza represents a separate build step, performed by a specific 'builder'.
53+
## The key of each stanza is the builder to use; this must be one of the
54+
## available builders.
55+
## The value of each stanza is a dictionary of settings for the builder that
56+
## outputs to that directory.
57+
## Keys in all settings dictionary are:
58+
## * 'output_dir' - determines output subdirectory for builder instance
59+
## relative to --output-directory
60+
## * 'name' - used when referencing the built docs from the index.
61+
62+
- doxygen: {
63+
# name: 'tf2_bullet Public C/C++ API',
64+
# output_dir: 'generated/doxygen',
65+
## file name for a user-supplied Doxyfile
66+
# doxyfile: null,
67+
## additional statements to add to the Doxyfile, list of strings
68+
extra_doxyfile_statements: ['TAGFILES = ""'],
69+
## location of include files for Doxygen. By default, rosdoc2 searches in
70+
## 'include', 'src', '<package.name>'
71+
# doxygen_input_dir: null,
72+
}
73+
- sphinx: {
74+
# name: 'tf2_bullet',
75+
## This path is relative to output staging.
76+
# doxygen_xml_directory: 'generated/doxygen/xml',
77+
# output_dir: '',
78+
## If sphinx_sourcedir is specified and not null, then the documentation in that folder
79+
## (specified relative to the package.xml directory) will replace rosdoc2's normal output.
80+
## If sphinx_sourcedir is left unspecified, any documentation found in the doc/ or
81+
## doc/source/ folder will still be included by default, along with other relevant package
82+
## information.
83+
# sphinx_sourcedir: null,
84+
## Directory (relative to the package.xml directory) where user documentation is found. If
85+
## documentation is in one of the standard locations (doc/ or doc/source) this is not
86+
## needed. Unlike sphinx_sourcedir, specifying this does not override the standard rosdoc2
87+
## output, but includes this user documentation along with other items included by default
88+
## by rosdoc2.
89+
## If the value is null, any found documentation in doc/ or doc/source/ is ignored.
90+
# user_doc_dir: 'doc'
91+
}

‎tf2_eigen/package.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,5 +28,6 @@
2828

2929
<export>
3030
<build_type>ament_cmake</build_type>
31+
<rosdoc2>rosdoc2.yaml</rosdoc2>
3132
</export>
3233
</package>

‎tf2_eigen/rosdoc2.yaml‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
## Default configuration, generated by rosdoc2.
2+
3+
## This 'attic section' self-documents this file's type and version.
4+
type: 'rosdoc2 config'
5+
version: 1
6+
7+
---
8+
9+
settings: {
10+
## This setting is relevant mostly if the standard Python package layout cannot
11+
## be assumed for 'sphinx-apidoc' invocation. The user can provide the path
12+
## (relative to the 'package.xml' file) where the Python modules defined by this
13+
## package are located.
14+
# python_source: 'tf2_eigen',
15+
16+
## This setting, if true, attempts to run `doxygen` and the `breathe`/`exhale`
17+
## extensions to `sphinx` regardless of build type. This is most useful if the
18+
## user would like to generate C/C++ API documentation for a package that is not
19+
## of the `ament_cmake/cmake` build type.
20+
# always_run_doxygen: false,
21+
22+
## This setting, if true, will skip running doxygen` and the `breathe`/`exhale`
23+
## extensions to `sphinx` regardless of build type. This is most useful if the
24+
## user has generated C++ documentation elsewhere that is included in the doc
25+
## folder, or in external documentation.
26+
# never_run_doxygen: false,
27+
28+
## This setting, if true, attempts to run `sphinx-apidoc` regardless of build
29+
## type. This is most useful if the user would like to generate Python API
30+
## documentation for a package that is not of the `ament_python` build type.
31+
# always_run_sphinx_apidoc: false,
32+
33+
## This setting, if true, will skip running `sphinx-apidoc` regardless of build
34+
## type. This is most useful if the user has generated python documentation elsewhere
35+
## that is included in the doc folder, or in external documentation.
36+
# never_run_sphinx_apidoc: false,
37+
38+
## This setting, if provided, will override the build_type of this package
39+
## for documentation purposes only. If not provided, documentation will be
40+
## generated assuming the build_type in package.xml.
41+
# override_build_type: 'ament_cmake',
42+
43+
## This setting, if true, will skip using breathe to process the C++ documentation, and
44+
# use the doxygen html instead. This is intended for cases where breathe is throwing
45+
# errors.
46+
# disable_breathe: false,
47+
48+
## This setting, if true, will display a link to the Doxygen html output.
49+
# show_doxygen_html: false,
50+
}
51+
builders:
52+
## Each stanza represents a separate build step, performed by a specific 'builder'.
53+
## The key of each stanza is the builder to use; this must be one of the
54+
## available builders.
55+
## The value of each stanza is a dictionary of settings for the builder that
56+
## outputs to that directory.
57+
## Keys in all settings dictionary are:
58+
## * 'output_dir' - determines output subdirectory for builder instance
59+
## relative to --output-directory
60+
## * 'name' - used when referencing the built docs from the index.
61+
62+
- doxygen: {
63+
# name: 'tf2_eigen Public C/C++ API',
64+
# output_dir: 'generated/doxygen',
65+
## file name for a user-supplied Doxyfile
66+
# doxyfile: null,
67+
## additional statements to add to the Doxyfile, list of strings
68+
extra_doxyfile_statements: ['TAGFILES = ""'],
69+
## location of include files for Doxygen. By default, rosdoc2 searches in
70+
## 'include', 'src', '<package.name>'
71+
# doxygen_input_dir: null,
72+
}
73+
- sphinx: {
74+
# name: 'tf2_eigen',
75+
## This path is relative to output staging.
76+
# doxygen_xml_directory: 'generated/doxygen/xml',
77+
# output_dir: '',
78+
## If sphinx_sourcedir is specified and not null, then the documentation in that folder
79+
## (specified relative to the package.xml directory) will replace rosdoc2's normal output.
80+
## If sphinx_sourcedir is left unspecified, any documentation found in the doc/ or
81+
## doc/source/ folder will still be included by default, along with other relevant package
82+
## information.
83+
# sphinx_sourcedir: null,
84+
## Directory (relative to the package.xml directory) where user documentation is found. If
85+
## documentation is in one of the standard locations (doc/ or doc/source) this is not
86+
## needed. Unlike sphinx_sourcedir, specifying this does not override the standard rosdoc2
87+
## output, but includes this user documentation along with other items included by default
88+
## by rosdoc2.
89+
## If the value is null, any found documentation in doc/ or doc/source/ is ignored.
90+
# user_doc_dir: 'doc'
91+
}

‎tf2_eigen_kdl/package.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,5 +35,6 @@
3535

3636
<export>
3737
<build_type>ament_cmake</build_type>
38+
<rosdoc2>rosdoc2.yaml</rosdoc2>
3839
</export>
3940
</package>

0 commit comments

Comments
 (0)