Unconditionally check exhale/breathe settings

In c6a6595, the `enable_exhale` and `enable_breathe` options were
evaluated only if the build type was `ament_cmake` or `cmake`.

Following the suggestion in
ros-infrastructure#28 (comment),
this commit reverts that change, and modifies the behavior such that the
values of `enable_exhale` and `enable_breathe` are always checked. The
only difference now is that previously, the default value for these
settings was `True`. Now, the default is determined by what the build
type is and what the `always_run_doxygen` setting has been set to.

Essentially, this commit allows users to explicitly enable
`enable_exhale` or `enable_breathe` and have those extensions invoked
regardless of the build type.

Signed-off-by: Abrar Rahman Protyasha <[email protected]>

rosdoc2/verbs/build/builders/sphinx_builder.py

@@ -80,50 +80,63 @@ def ensure_global(name, default):
 
 build_type = '{build_type}'
 always_run_doxygen = {always_run_doxygen}
-if build_type in ('ament_cmake', 'cmake') or always_run_doxygen:
- if rosdoc2_settings.get('enable_breathe', True):
- # Configure Breathe.
- # Breathe ingests the XML output from Doxygen and makes it accessible from Sphinx.
- print('[rosdoc2] enabling breathe', file=sys.stderr)
- ensure_global('breathe_projects', {{}})
- breathe_projects.update({{
- {breathe_projects}}})
- if breathe_projects:
- # Enable Breathe and arbitrarily select the first project.
- extensions.append('breathe')
- breathe_default_project = next(iter(breathe_projects.keys()))
-
- if rosdoc2_settings.get('enable_exhale', True):
- # Configure Exhale.
- # Exhale uses the output of Doxygen and Breathe to create easier to browse pages
- # for classes and functions documented with Doxygen.
- # This is similar to the class hierarchies and namespace listing provided by
- # Doxygen out of the box.
- print('[rosdoc2] enabling exhale', file=sys.stderr)
- extensions.append('exhale')
- ensure_global('exhale_args', {{}})
-
- from exhale import utils
- exhale_args.update({{
- # These arguments are required.
- "containmentFolder": "{user_sourcedir}/api",
- "rootFileName": "library_root.rst",
- "rootFileTitle": "{package_name} C/C++ API",
- "doxygenStripFromPath": "..",
- # Suggested optional arguments.
- "createTreeView": True,
- # TIP: if using the sphinx-bootstrap-theme, you need
- # "treeViewIsBootstrap": True,
- "exhaleExecutesDoxygen": False,
- # Maps markdown files to the "md" lexer, and not the "markdown" lexer
- # Pygments registers "md" as a valid markdown lexer, and not "markdown"
- "lexerMapping": {{r".*\.(md|markdown)$": "md",}},
- # This mapping will work when `exhale` supports `:doxygenpage:` directives
- # Check https://github.com/svenevs/exhale/issues/111
- # TODO(aprotyas): Uncomment the mapping below once the above issue is resolved.
- # "customSpecificationsMapping": utils.makeCustomSpecificationsMapping(
- # lambda kind: [":project:", ":path:", ":content-only:"] if kind == "page" else []),
- }})
+# By default, the `exhale`/`breathe` extensions should be added if `doxygen` was invoked
+is_doxygen_invoked = build_type in ('ament_cmake', 'cmake') or always_run_doxygen
+
+if rosdoc2_settings.get('enable_breathe', is_doxygen_invoked):
+ # Configure Breathe.
+ # Breathe ingests the XML output from Doxygen and makes it accessible from Sphinx.
+ print('[rosdoc2] enabling breathe', file=sys.stderr)
+ # First check that doxygen would have been run
+ if not is_doxygen_invoked:
+ raise RuntimeError(
+ "Cannot enable the 'breathe' extension if 'doxygen' is not invoked."
+ "Please enable 'always_run_doxygen' if the package is not an"
+ "'ament_cmake' or 'cmake' package.")
+ ensure_global('breathe_projects', {{}})
+ breathe_projects.update({{{breathe_projects}}})
+ if breathe_projects:
+ # Enable Breathe and arbitrarily select the first project.
+ extensions.append('breathe')
+ breathe_default_project = next(iter(breathe_projects.keys()))
+
+if rosdoc2_settings.get('enable_exhale', is_doxygen_invoked):
+ # Configure Exhale.
+ # Exhale uses the output of Doxygen and Breathe to create easier to browse pages
+ # for classes and functions documented with Doxygen.
+ # This is similar to the class hierarchies and namespace listing provided by
+ # Doxygen out of the box.
+ print('[rosdoc2] enabling exhale', file=sys.stderr)
+ # First check that doxygen would have been run
+ if not is_doxygen_invoked:
+ raise RuntimeError(
+ "Cannot enable the 'breathe' extension if 'doxygen' is not invoked."
+ "Please enable 'always_run_doxygen' if the package is not an"
+ "'ament_cmake' or 'cmake' package.")
+ extensions.append('exhale')
+ ensure_global('exhale_args', {{}})
+
+ from exhale import utils
+ exhale_args.update({{
+ # These arguments are required.
+ "containmentFolder": "{user_sourcedir}/api",
+ "rootFileName": "library_root.rst",
+ "rootFileTitle": "{package_name} C/C++ API",
+ "doxygenStripFromPath": "..",
+ # Suggested optional arguments.
+ "createTreeView": True,
+ # TIP: if using the sphinx-bootstrap-theme, you need
+ # "treeViewIsBootstrap": True,
+ "exhaleExecutesDoxygen": False,
+ # Maps markdown files to the "md" lexer, and not the "markdown" lexer
+ # Pygments registers "md" as a valid markdown lexer, and not "markdown"
+ "lexerMapping": {{r".*\.(md|markdown)$": "md",}},
+ # This mapping will work when `exhale` supports `:doxygenpage:` directives
+ # Check https://github.com/svenevs/exhale/issues/111
+ # TODO(aprotyas): Uncomment the mapping below once the above issue is resolved.
+ # "customSpecificationsMapping": utils.makeCustomSpecificationsMapping(
+ # lambda kind: [":project:", ":path:", ":content-only:"] if kind == "page" else []),
+ }})
 
 if rosdoc2_settings.get('override_theme', True):
  extensions.append('sphinx_rtd_theme')