Merge pull request #75 from rkent/allow-ament-cmake-python

Allow ament-cmake-python build types

rosdoc2/verbs/build/build_context.py

@@ -30,3 +30,4 @@ def __init__(self, *, configuration_file_path, package_object, tool_options):
         self.python_source = None
         self.always_run_doxygen = False
         self.always_run_sphinx_apidoc = False
+        self.ament_cmake_python = False

rosdoc2/verbs/build/builders/sphinx_builder.py

@@ -37,13 +37,14 @@ def generate_package_toc_entry(*, build_context) -> str:
     build_type = build_context.build_type
     always_run_doxygen = build_context.always_run_doxygen
     always_run_sphinx_apidoc = build_context.always_run_sphinx_apidoc
+    ament_cmake_python = build_context.ament_cmake_python
     # The TOC entries have to be indented by three (or any N) spaces
     # inside the string to fall under the `:toctree:` directive
-    toc_entry_cpp = f'{build_context.package.name} <generated/index>\n'
-    toc_entry_py = f'{build_context.package.name} <modules>\n'
-    toc_entry = ''
+    toc_entry_cpp = '   C++ API <generated/index>\n'
+    toc_entry_py = '   Python API <modules>\n'
+    toc_entry = '\n'
 
-    if build_type == 'ament_python' or always_run_sphinx_apidoc:
+    if build_type == 'ament_python' or always_run_sphinx_apidoc or ament_cmake_python:
         toc_entry += toc_entry_py
     if build_type in ['ament_cmake', 'cmake'] or always_run_doxygen:
         toc_entry += toc_entry_cpp
@@ -152,12 +153,13 @@ def ensure_global(name, default):
         # These arguments are required.
         "containmentFolder": "{user_sourcedir}/generated",
         "rootFileName": "index.rst",
+        "rootFileTitle": "C++ API",
         "doxygenStripFromPath": "..",
         # Suggested optional arguments.
         "createTreeView": True,
         "fullToctreeMaxDepth": 1,
         "unabridgedOrphanKinds": [],
-        "fullApiSubSectionTitle": "Reference",
+        "fullApiSubSectionTitle": "Full C++ API",
         # TIP: if using the sphinx-bootstrap-theme, you need
         # "treeViewIsBootstrap": True,
         "exhaleExecutesDoxygen": False,
@@ -328,8 +330,7 @@ def ensure_global(name, default):
 
 .. toctree::
    :maxdepth: 2
-
-   {package_toc_entry}
+{package_toc_entry}
 
 Indices and Search
 ==================
@@ -472,13 +473,11 @@ def build(self, *, doc_build_folder, output_staging_directory):
             package_src_directory,
             intersphinx_mapping_extensions)
 
-        # If the package has build type `ament_python`, or if the user configured
-        # to run `sphinx-apidoc`, then invoke `sphinx-apidoc` before building
-        if (
-            self.build_context.build_type == 'ament_python'
-            or self.build_context.always_run_sphinx_apidoc
-        ):
-
+        # If the package has python code, then invoke `sphinx-apidoc` before building
+        has_python = self.build_context.build_type == 'ament_python' or \
+            self.build_context.always_run_sphinx_apidoc or \
+            self.build_context.ament_cmake_python
+        if has_python:
             if not package_src_directory or not os.path.isdir(package_src_directory):
                 raise RuntimeError(
                     'Could not locate source directory to invoke sphinx-apidoc in. '

rosdoc2/verbs/build/inspect_package_for_settings.py

@@ -134,4 +134,10 @@ def inspect_package_for_settings(package, tool_options):
         package_object=package,
         tool_options=tool_options,
     )
+
+    # Is this python under ament_cmake?
+    for depends in package['buildtool_depends']:
+        if str(depends) == 'ament_cmake_python':
+            build_context.ament_cmake_python = True
+
     return parse_rosdoc2_yaml(rosdoc_config_file, build_context)

test/test_builder.py

@@ -193,13 +193,20 @@ def test_full_package(session_dir):
 
     includes = [
         PKG_NAME,
+        'python api',
+        'c++ api',
     ]
     file_includes = [
         'generated/index.html'
     ]
+    links_exist = [
+        'full_package.dummy.html',
+        'modules.html',
+    ]
     do_test_package(PKG_NAME, session_dir,
                     includes=includes,
-                    file_includes=file_includes)
+                    file_includes=file_includes,
+                    links_exist=links_exist)
 
 
 def test_only_python(session_dir):