Interpret enable_breathe and enable_exhale as never_run_doxygen option.

rosdoc2/verbs/build/inspect_package_for_settings.py

@@ -178,6 +178,19 @@ def inspect_package_for_settings(package, tool_options):
         <another_package_name>
             <valid rosdoc2.yaml>
     """
+
+    # Over 10 packages incorrectly use enable_breathe=false and enable_exhale=false to mean
+    # "Don't parse my code for documentation" Detect those, give a warning, and interpret
+    # this as never_run_doxygen and never_run_sphinx_apidoc
+    if 'enable_breathe' in settings_dict or 'enable_exhale' in settings_dict:
+        logger.warning('rosdoc2.yaml contains enable_breathe or enable_exhale, which are not '
+                       'valid. If false, these will be interpreted to mean "never_run_doxygen='
+                       'true". This conversion is DEPRECATED and may be removed after 2025.')
+        if not settings_dict.get('enable_breathe', True) or \
+           not settings_dict.get('enable_exhale', True):
+            if 'never_run_doxygen' not in settings_dict:
+                settings_dict['never_run_doxygen'] = True
+
     yaml_extend = tool_options.yaml_extend
     if yaml_extend:
         if not os.path.isfile(yaml_extend):

test/packages/basic_cpp/Doxyfile

@@ -0,0 +1,21 @@
+# All settings not listed here will use the Doxygen default values.
+
+PROJECT_NAME           = "urdf"
+PROJECT_NUMBER         = ros2
+PROJECT_BRIEF          = "C++ parser for the Unified Robot Description Format (URDF)"
+
+INPUT                  = ./include
+RECURSIVE              = YES
+OUTPUT_DIRECTORY       = docs_output
+
+EXTRACT_ALL            = YES
+SORT_MEMBER_DOCS       = NO
+
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+EXCLUDE_SYMBOLS        = detail details
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             += URDF_EXPORT

test/packages/false_python/rosdoc2.yaml

@@ -28,6 +28,11 @@ settings: {
     ## for documentation purposes only. If not provided, documentation will be
     ## generated assuming the build_type in package.xml.
     # override_build_type: 'ament_python',
+
+    # These are invalid, but (deprecated) interpreted as never_run options. Include
+    # in this test so we can see the generated warning.
+    enable_breathe: false,
+    enable_exhale: false,
 }
 builders:
     ## Each stanza represents a separate build step, performed by a specific 'builder'.