Allow null user_doc_dir to ignore documentation. (#153)

Signed-off-by: R. Kent James <[email protected]>

rosdoc2/verbs/build/builders/sphinx_builder.py

@@ -354,6 +354,9 @@ def ensure_global(name, default):
 }}
 """
 
+# Special value for user_doc_dir if specified to ignore
+IGNORE_DOC_DIRECTORY = '__ignore__'
+
 
 class SphinxBuilder(Builder):
     """
@@ -415,12 +418,17 @@ def __init__(self, builder_name, builder_entry_dictionary, build_context):
                 logger.info(f'The user specified sphinx_sourcedir as {value}')
                 self.sphinx_sourcedir = value
             elif key == 'user_doc_dir':
-                if not os.path.isdir(os.path.join(configuration_file_dir, value)):
-                    raise RuntimeError(
-                        f"Error user documentation directory '{value}' does not exist relative "
-                        f"to '{configuration_file_path}', or is not a directory.")
                 logger.info(f'The user specified user_doc_dir as {value}')
-                self.user_doc_dir = value
+                if value is not None:
+                    if not os.path.isdir(os.path.join(configuration_file_dir, value)):
+                        raise RuntimeError(
+                            f"Error user documentation directory '{value}' does not exist "
+                            f"relative to '{configuration_file_path}', or is not a directory.")
+                    self.user_doc_dir = value
+                else:
+                    # We have to be able to distinguish between no value set, and value set to null
+                    # (python None). We use a unique string for this.
+                    self.user_doc_dir = IGNORE_DOC_DIRECTORY
             else:
                 raise RuntimeError(f"Error the Sphinx builder does not support key '{key}'")
 
@@ -514,7 +522,9 @@ def build(self, *, doc_build_folder, output_staging_directory):
                 print(f'Failed to copy user content: {e}')
         else:
             # include user documentation
-            if self.user_doc_dir:
+            if self.user_doc_dir == IGNORE_DOC_DIRECTORY:
+                user_doc_dir = None
+            elif self.user_doc_dir:
                 user_doc_dir = self.user_doc_dir
             else:
                 # If the user does not supply a doc directory, check the standard locations.

rosdoc2/verbs/build/inspect_package_for_settings.py

@@ -102,6 +102,7 @@
         ## needed. Unlike sphinx_sourcedir, specifying this does not override the standard rosdoc2
         ## output, but includes this user documentation along with other items included by default
         ## by rosdoc2.
+        ## If the value is null, any found documentation in doc/ or doc/source/ is ignored.
         # user_doc_dir: 'doc'
       }}
 """

test/packages/ignore_doc/doc/noshow.md

@@ -0,0 +1,2 @@
+# Do not show
+rosdoc2.yaml for this packages has user_doc_dir=null so do not show this.

test/packages/ignore_doc/package.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>ignore_doc</name>
+  <version>0.1.2</version>
+  <description>I have a doc directory, but do not show</description>
+  <maintainer email="[email protected]">Some One</maintainer>
+  <license>Apache License 2.0</license>
+  <export>
+    <build_type>ament_cmake</build_type>
+    <rosdoc2>rosdoc2.yaml</rosdoc2>
+  </export>
+</package>

test/packages/ignore_doc/rosdoc2.yaml

@@ -0,0 +1,11 @@
+type: 'rosdoc2 config'
+version: 1
+---
+settings: {
+}
+builders:
+    - doxygen: {
+      }
+    - sphinx: {
+        user_doc_dir: null
+      }

test/test_builder.py

@@ -300,3 +300,13 @@ def test_src_alt_python(module_dir):
     do_test_package(PKG_NAME, module_dir,
                     includes=includes,
                     links_exist=links_exist)
+
+
+def test_ignore_doc(module_dir):
+    """Tests of a package with doc directory, but rosdoc2.yaml says ignore."""
+    PKG_NAME = 'ignore_doc'
+    do_build_package(DATAPATH / PKG_NAME, module_dir)
+
+    excludes = ['do not show']
+
+    do_test_package(PKG_NAME, module_dir, excludes=excludes)