Skip to content

Commit 2f5485f

Browse files
rkentrkent
committed
Add show_exec_dep to rosdoc2.yaml, avoid 'meta' name
1 parent 51d2faf commit 2f5485f

File tree

9 files changed

+240
-22
lines changed

9 files changed

+240
-22
lines changed

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

+7-6
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,14 @@
2121
{% if interface_counts['srv'] > 0 %} Service Definitions <interfaces/service_definitions>{% endif %}
2222
{% if interface_counts['action'] > 0 %} Action Definitions <interfaces/action_definitions>{% endif %}
2323
{% if has_standard_docs %} Standard Documents <standards>{% endif %}
24-
{% if is_meta %}
25-
Dependencies of this META package
26-
---------------------------------
27-
{% for dependency in package.exec_depends %}
24+
{% if show_exec_dep %}
25+
26+
Execution Dependencies of this package
27+
--------------------------------------
28+
{% for dependency in package.exec_depends -%}
2829
* `{{ dependency }} <{{ base_url }}/{{ dependency }}>`_
29-
{% endfor %}
30-
{% endif %}
30+
{% endfor -%}
31+
{% endif -%}
3132

3233
{% if has_documentation %}
3334
.. toctree::

‎rosdoc2/verbs/build/builders/sphinx_builder.py

+23-13
Original file line numberDiff line numberDiff line change
@@ -474,19 +474,29 @@ def build(self, *, doc_build_folder, output_staging_directory):
474474
has_cpp = build_context.build_type in ['ament_cmake', 'cmake'] or always_run_doxygen
475475
package = self.build_context.package
476476

477-
# Detect meta packages. They have no build_dependencies, do have exec_dependencies,
478-
# and have no subdirectories except for possibly 'doc'.
479-
is_meta = True
480-
if package.build_depends or not package.exec_depends:
481-
is_meta = False
477+
show_exec_dep = build_context.show_exec_dep
478+
if show_exec_dep is None:
479+
if package.is_metapackage():
480+
show_exec_dep = True
481+
logger.info('show_exec_dep set True because is_metapackage set in package.xml')
482+
# Detect meta packages. They have no build_dependencies, do have exec_dependencies,
483+
# and have no subdirectories except for possibly 'doc'.
484+
elif package.build_depends or not package.exec_depends:
485+
show_exec_dep = False
486+
logger.info("show_exec_dep set False because depends don't match meta pattern")
487+
else:
488+
pp = Path(package_xml_directory)
489+
subdirectories = [x for x in pp.iterdir() if x.is_dir()]
490+
for subdirectory in subdirectories:
491+
if subdirectory.name != 'doc':
492+
show_exec_dep = False
493+
logger.info('show_exec_dep set False because non-"doc/" directory found')
494+
continue
495+
if show_exec_dep is None:
496+
show_exec_dep = True
497+
logger.info('show_exec_dep set True as package matches meta pattern')
482498
else:
483-
pp = Path(package_xml_directory)
484-
subdirectories = [x for x in pp.iterdir() if x.is_dir()]
485-
for subdirectory in subdirectories:
486-
if subdirectory.name != 'doc':
487-
is_meta = False
488-
continue
489-
499+
logger.info(f'show_exec_dep set to {show_exec_dep} in rosdoc2.yml')
490500
self.template_variables.update({
491501
'has_python': has_python,
492502
'has_cpp': has_cpp,
@@ -496,7 +506,7 @@ def build(self, *, doc_build_folder, output_staging_directory):
496506
'interface_counts': interface_counts,
497507
'package': package,
498508
'base_url': base_url,
499-
'is_meta': is_meta or package.is_metapackage(),
509+
'show_exec_dep': show_exec_dep,
500510
})
501511

502512
# Setup rosdoc2 Sphinx file which will include and extend the one in

‎rosdoc2/verbs/build/inspect_package_for_settings.py

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

‎rosdoc2/verbs/build/parse_rosdoc2_yaml.py

+1
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ def parse_rosdoc2_yaml(yaml_string, build_context):
6161
build_context.always_run_doxygen = settings_dict.get('always_run_doxygen', False)
6262
build_context.always_run_sphinx_apidoc = settings_dict.get('always_run_sphinx_apidoc', False)
6363
build_context.build_type = settings_dict.get('override_build_type', build_context.build_type)
64+
build_context.show_exec_dep = settings_dict.get('show_exec_dep', None)
6465

6566
if 'builders' not in config:
6667
raise ValueError(

‎test/packages/do_show_dep/package.xml

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?xml version="1.0"?>
2+
<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
3+
<package format="3">
4+
<name>do_show_dep</name>
5+
<version>0.1.2</version>
6+
<description>forcing show of exec dependencies</description>
7+
<maintainer email="[email protected]">Some One</maintainer>
8+
<license>Apache License 2.0</license>
9+
<depend>basic_cpp</depend>
10+
<exec_depend>full_package</exec_depend>
11+
<exec_depend>minimum_package</exec_depend>
12+
<exec_depend>only_messages</exec_depend>
13+
<exec_depend>only_python</exec_depend>
14+
<export>
15+
<rosdoc2>rosdoc2.yaml</rosdoc2>
16+
</export>
17+
</package>

‎test/packages/do_show_dep/rosdoc2.yaml

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
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, if true, attempts to run `doxygen` and the `breathe`/`exhale`
28+
## extensions to `sphinx` regardless of build type. This is most useful if the
29+
## user would like to generate C/C++ API documentation for a package that is not
30+
## of the `ament_cmake/cmake` build type.
31+
always_run_doxygen: false
32+
33+
## This setting, if true, attempts to run `sphinx-apidoc` regardless of build
34+
## type. This is most useful if the user would like to generate Python API
35+
## documentation for a package that is not of the `ament_python` build type.
36+
always_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_python'
42+
43+
# This boolean setting, if provided, determines whether the external dependencies of a package
44+
# are shown in the home page of the documentation, which is useful for packages that are only
45+
# used to force loading of other packages (which are sometimes called meta packages).
46+
# If not set, then the decision to show the external dependencies is made on the following
47+
# heuristics: show if the package has no build_depend, does have exec_depend, and has no
48+
# subdirectories except an optional doc/ subdirectory.
49+
show_exec_dep: true
50+
builders:
51+
## Each stanza represents a separate build step, performed by a specific 'builder'.
52+
## The key of each stanza is the builder to use; this must be one of the
53+
## available builders.
54+
## The value of each stanza is a dictionary of settings for the builder that
55+
## outputs to that directory.
56+
## Required keys in the settings dictionary are:
57+
## * 'output_dir' - determines output subdirectory for builder instance
58+
## relative to --output-directory
59+
## * 'name' - used when referencing the built docs from the index.
60+
61+
- doxygen: {
62+
name: 'forcing show of exec dependecies',
63+
output_dir: 'generated/doxygen'
64+
}
65+
- sphinx: {
66+
name: 'do_show_dep',
67+
## This path is relative to output staging.
68+
doxygen_xml_directory: 'generated/doxygen/xml',
69+
output_dir: ''
70+
}

‎test/packages/dont_show_dep/package.xml

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?xml version="1.0"?>
2+
<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
3+
<package format="3">
4+
<name>dont_show_dep</name>
5+
<version>0.1.2</version>
6+
<description>explicitly not showing dependencies</description>
7+
<maintainer email="[email protected]">Some One</maintainer>
8+
<license>Apache License 2.0</license>
9+
<exec_depend>basic_cpp</exec_depend>
10+
<exec_depend>full_package</exec_depend>
11+
<exec_depend>minimum_package</exec_depend>
12+
<exec_depend>only_messages</exec_depend>
13+
<exec_depend>only_python</exec_depend>
14+
<export>
15+
<rosdoc2>rosdoc2.yaml</rosdoc2>
16+
</export>
17+
</package>

‎test/packages/dont_show_dep/rosdoc2.yaml

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
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, if true, attempts to run `doxygen` and the `breathe`/`exhale`
28+
## extensions to `sphinx` regardless of build type. This is most useful if the
29+
## user would like to generate C/C++ API documentation for a package that is not
30+
## of the `ament_cmake/cmake` build type.
31+
always_run_doxygen: false
32+
33+
## This setting, if true, attempts to run `sphinx-apidoc` regardless of build
34+
## type. This is most useful if the user would like to generate Python API
35+
## documentation for a package that is not of the `ament_python` build type.
36+
always_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_python'
42+
43+
# This boolean setting, if provided, determines whether the external dependencies of a package
44+
# are shown in the home page of the documentation, which is useful for packages that are only
45+
# used to force loading of other packages (which are sometimes called meta packages).
46+
# If not set, then the decision to show the external dependencies is made on the following
47+
# heuristics: show if the package has no build_depend, does have exec_depend, and has no
48+
# subdirectories except an optional doc/ subdirectory.
49+
show_exec_dep: false
50+
builders:
51+
## Each stanza represents a separate build step, performed by a specific 'builder'.
52+
## The key of each stanza is the builder to use; this must be one of the
53+
## available builders.
54+
## The value of each stanza is a dictionary of settings for the builder that
55+
## outputs to that directory.
56+
## Required keys in the settings dictionary are:
57+
## * 'output_dir' - determines output subdirectory for builder instance
58+
## relative to --output-directory
59+
## * 'name' - used when referencing the built docs from the index.
60+
61+
- doxygen: {
62+
name: 'explicitly not showing dependencies',
63+
output_dir: 'generated/doxygen'
64+
}
65+
- sphinx: {
66+
name: 'dont_show_dep',
67+
## This path is relative to output staging.
68+
doxygen_xml_directory: 'generated/doxygen/xml',
69+
output_dir: ''
70+
}

‎test/test_builder.py

+27-3
Original file line numberDiff line numberDiff line change
@@ -184,8 +184,8 @@ def test_minimum_package(session_dir):
184184
]
185185
excludes = [
186186
'classes and structs', # only found in C++ projects
187-
'dependencies of this meta package', # only in meta packages
188-
'links', # only found if urls defined
187+
'links', # only found if urls defined,
188+
'execution dependencies of this package', # only in meta packages
189189
]
190190
file_includes = [
191191
'search.html',
@@ -307,7 +307,31 @@ def test_meta_package(session_dir):
307307
do_build_package(DATAPATH / PKG_NAME, session_dir)
308308

309309
includes = [
310-
'dependencies of this meta package',
310+
'execution dependencies of this package',
311311
'only_python',
312312
]
313313
do_test_package(PKG_NAME, session_dir, includes=includes)
314+
315+
316+
def test_do_show_dep(session_dir):
317+
"""Tests rosdoc2.yaml with show_exec_dep=true."""
318+
PKG_NAME = 'do_show_dep'
319+
320+
do_build_package(DATAPATH / PKG_NAME, session_dir)
321+
322+
includes = [
323+
'execution dependencies of this package',
324+
]
325+
do_test_package(PKG_NAME, session_dir, includes=includes)
326+
327+
328+
def test_dont_show_dep(session_dir):
329+
"""Tests rosdoc2.yaml with show_exec_dep=false."""
330+
PKG_NAME = 'dont_show_dep'
331+
332+
do_build_package(DATAPATH / PKG_NAME, session_dir)
333+
334+
excludes = [
335+
'execution dependencies of this package',
336+
]
337+
do_test_package(PKG_NAME, session_dir, excludes=excludes)

0 commit comments

Comments
 (0)