Add basic c++ test with custom conf.py

rosdoc2/verbs/build/builders/sphinx_builder.py

@@ -679,6 +679,5 @@ def generate_wrapping_rosdoc2_sphinx_project_into_directory(
             'package_version_short': '.'.join(package.version.split('.')[0:2]),
         })
 
-        print(os.path.abspath(os.path.join(wrapped_sphinx_directory, 'conf.py')))
         with open(os.path.join(wrapped_sphinx_directory, 'conf.py'), 'w+') as f:
             f.write(rosdoc2_wrapping_conf_py_template.format_map(self.template_variables))

test/packages/basic_cpp/CMakeLists.txt

@@ -0,0 +1,35 @@
+cmake_minimum_required(VERSION 3.8)
+project(basic_cpp)
+
+if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  add_compile_options(-Wall -Wextra -Wpedantic)
+endif()
+
+# find dependencies
+find_package(ament_cmake REQUIRED)
+# uncomment the following section in order to fill in
+# further dependencies manually.
+# find_package(<dependency> REQUIRED)
+
+add_executable(test_node src/test_node.cpp)
+target_include_directories(test_node PUBLIC
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+  $<INSTALL_INTERFACE:include/${PROJECT_NAME}>)
+target_compile_features(test_node PUBLIC c_std_99 cxx_std_17)  # Require C99 and C++17
+
+install(TARGETS test_node
+  DESTINATION lib/${PROJECT_NAME})
+
+if(BUILD_TESTING)
+  find_package(ament_lint_auto REQUIRED)
+  # the following line skips the linter which checks for copyrights
+  # comment the line when a copyright and license is added to all source files
+  set(ament_cmake_copyright_FOUND TRUE)
+  # the following line skips cpplint (only works in a git repo)
+  # comment the line when this package is in a git repo and when
+  # a copyright and license is added to all source files
+  set(ament_cmake_cpplint_FOUND TRUE)
+  ament_lint_auto_find_test_dependencies()
+endif()
+
+ament_package()

test/packages/basic_cpp/doc/conf.py

@@ -0,0 +1,128 @@
+# Configuration file for the Sphinx documentation builder.
+# This was copied from a generated conf.py, and flake8 does not like it.
+# flake8: noqa
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath(os.path.join('/home/kent/github/rkent/rosdoc2/test/packages/basic_cpp/basic_cpp', '..')))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'basic_cpp_and_more'
+copyright = '2024, Dummy User'
+author = 'Custom User'
+print('[basic cpp] config.py')
+
+# The full version, including alpha/beta/rc tags
+release = '0.0.0'
+
+version = '0.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+## rosdoc2 will extend the extensions to enable Breathe and Exhale if you
+## do not add them here, as well as others, perhaps.
+## If you add them manually rosdoc2 may still try to configure them.
+## See the rosdoc2_settings below for some options on avoiding that.
+extensions = [
+    'sphinx_rtd_theme',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+master_doc = 'index'
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+    '.markdown': 'markdown',
+}
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+## rosdoc2 will override the theme, but you may set one here for running Sphinx
+## without the rosdoc2 tool.
+html_theme = 'sphinx_rtd_theme'
+
+html_theme_options = {
+    # Toc options
+    'collapse_navigation': False,
+    'sticky_navigation': True,
+    'navigation_depth': -1,
+    'includehidden': True,
+    'titles_only': False,
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+## rosdoc2 comments this out by default because we're not creating it.
+# html_static_path = ['_static']
+
+# -- Options for rosdoc2 -----------------------------------------------------
+
+## These settings are specific to rosdoc2, and if Sphinx is run without rosdoc2
+## they will be safely ignored.
+## None are required by default, so the lines below show the default values,
+## therefore you will need to uncomment the lines and change their value
+## if you want change the behavior of rosdoc2.
+rosdoc2_settings = {
+    ## This setting, if True, will ensure breathe is part of the 'extensions',
+    ## and will set all of the breathe configurations, if not set, and override
+    ## settings as needed if they are set by this configuration.
+    # 'enable_breathe': True,
+
+    ## This setting, if True, will ensure exhale is part of the 'extensions',
+    ## and will set all of the exhale configurations, if not set, and override
+    ## settings as needed if they are set by this configuration.
+    # 'enable_exhale': True,
+
+    ## This setting, if provided, allows option specification for breathe
+    ## directives through exhale. If not set, exhale defaults will be used.
+    ## If an empty dictionary is provided, breathe defaults will be used.
+    # 'exhale_specs_mapping': {},
+
+    ## This setting, if True, will ensure autodoc is part of the 'extensions'.
+    # 'enable_autodoc': True,
+
+    ## This setting, if True, will ensure intersphinx is part of the 'extensions'.
+    # 'enable_intersphinx': True,
+
+    ## This setting, if True, will have the 'html_theme' overridden to provide
+    ## a consistent style across all of the ROS documentation.
+    # 'override_theme': True,
+
+    ## This setting, if True, will automatically extend the intersphinx mapping
+    ## using inventory files found in the cross-reference directory.
+    ## If false, the `found_intersphinx_mappings` variable will be in the global
+    ## scope when run with rosdoc2, and could be conditionally used in your own
+    ## Sphinx conf.py file.
+    # 'automatically_extend_intersphinx_mapping': True,
+
+    ## Support markdown
+    # 'support_markdown': True,
+}

test/packages/basic_cpp/doc/index.rst

@@ -0,0 +1,16 @@
+Welcome to the documentation for basic_cpp
+==========================================
+
+.. toctree::
+   :maxdepth: 2
+
+   C++ API <generated/index>
+   A Different Title <overview>
+
+
+Indices and Search
+==================
+
+* :ref:`genindex`
+* :ref:`search`
+

test/packages/basic_cpp/doc/overview.markdown

@@ -0,0 +1,3 @@
+# Overview
+
+This documentation demos a custom conf.py

test/packages/basic_cpp/include/basic_cpp/test_node.hpp

@@ -0,0 +1,27 @@
+//
+//   Copyright 2024 R. Kent James <[email protected]>
+//
+//   Licensed under the Apache License, Version 2.0 (the "License");
+//   you may not use this file except in compliance with the License.
+//   You may obtain a copy of the License at
+//
+//       http://www.apache.org/licenses/LICENSE-2.0
+//
+//   Unless required by applicable law or agreed to in writing, software
+//   distributed under the License is distributed on an "AS IS" BASIS,
+//   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//   See the License for the specific language governing permissions and
+//   limitations under the License.
+
+#ifndef BASIC_CPP__TEST_NODE_HPP_
+#define BASIC_CPP__TEST_NODE_HPP_
+
+/// @file
+/// @brief This is an include file to go with the C++ file generated by `ros2 pkg create`
+
+/**
+  This demo program just prints hello world.
+  */
+int main(int argc, char ** argv)
+
+#endif  // BASIC_CPP__TEST_NODE_HPP_

test/packages/basic_cpp/package.xml

@@ -0,0 +1,18 @@
+<?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>basic_cpp</name>
+  <version>0.0.0</version>
+  <description>Basic c++ package using ros2 pkg create</description>
+  <maintainer email="[email protected]">ros2 user</maintainer>
+  <license>Apache 2.0</license>
+
+  <buildtool_depend>ament_cmake</buildtool_depend>
+
+  <test_depend>ament_lint_auto</test_depend>
+  <test_depend>ament_lint_common</test_depend>
+
+  <export>
+    <build_type>ament_cmake</build_type>
+  </export>
+</package>

test/packages/basic_cpp/rosdoc2.yaml

@@ -0,0 +1,68 @@
+## Default configuration, generated by rosdoc2.
+
+## This 'attic section' self-documents this file's type and version.
+type: 'rosdoc2 config'
+version: 1
+
+---
+
+settings:
+    ## If this is true, a standard index page is generated in the output directory.
+    ## It uses the package information from the 'package.xml' to show details
+    ## about the package, creates a table of contents for the various builders
+    ## that were run, and may contain links to things like build farm jobs for
+    ## this package or links to other versions of this package.
+
+    ## If false, you can still include content that would have been in the index
+    ## into one of your '.rst' files from your Sphinx project, using the
+    ## '.. include::' directive in Sphinx.
+    ## For example, you could include it in a custom 'index.rst' so you can have
+    ## the standard information followed by custom content.
+
+    ## TODO(wjwwood): provide a concrete example of this (relative path?)
+
+    ## If this is not specified explicitly, it defaults to 'true'.
+    generate_package_index: true
+
+    ## This setting is relevant mostly if the standard Python package layout cannot
+    ## be assumed for 'sphinx-apidoc' invocation. The user can provide the path
+    ## (relative to the 'package.xml' file) where the Python modules defined by this
+    ## package are located.
+    python_source: 'basic_cpp'
+
+    ## This setting, if true, attempts to run `doxygen` and the `breathe`/`exhale`
+    ## extensions to `sphinx` regardless of build type. This is most useful if the
+    ## user would like to generate C/C++ API documentation for a package that is not
+    ## of the `ament_cmake/cmake` build type.
+    always_run_doxygen: false
+
+    ## This setting, if true, attempts to run `sphinx-apidoc` regardless of build
+    ## type. This is most useful if the user would like to generate Python API
+    ## documentation for a package that is not of the `ament_python` build type.
+    always_run_sphinx_apidoc: false
+
+    # This setting, if provided, will override the build_type of this package
+    # for documentation purposes only. If not provided, documentation will be
+    # generated assuming the build_type in package.xml.
+    # override_build_type: 'ament_python'
+builders:
+    ## Each stanza represents a separate build step, performed by a specific 'builder'.
+    ## The key of each stanza is the builder to use; this must be one of the
+    ## available builders.
+    ## The value of each stanza is a dictionary of settings for the builder that
+    ## outputs to that directory.
+    ## Required keys in the settings dictionary are:
+    ##  * 'output_dir' - determines output subdirectory for builder instance
+    ##                   relative to --output-directory
+    ##  * 'name' - used when referencing the built docs from the index.
+
+    - doxygen: {
+        name: 'basic_cpp Public C/C++ API',
+        output_dir: 'generated/doxygen'
+    }
+    - sphinx: {
+        name: 'basic_cpp',
+        ## This path is relative to output staging.
+        doxygen_xml_directory: 'generated/doxygen/xml',
+        output_dir: ''
+    }

test/packages/basic_cpp/src/test_node.cpp

@@ -0,0 +1,10 @@
+#include <cstdio>
+
+int main(int argc, char ** argv)
+{
+  (void) argc;
+  (void) argv;
+
+  printf("hello world basic_cpp package\n");
+  return 0;
+}

test/test_builder.py

@@ -243,3 +243,23 @@ def test_only_messages(session_dir):
     links_exist = ['generated/msg/NumPwrResult.html']
 
     do_test_package(PKG_NAME, session_dir, includes=includes, links_exist=links_exist)
+
+
+def test_basic_cpp(session_dir):
+    """Test a basic C++ package."""
+    PKG_NAME = 'basic_cpp'
+
+    do_build_package(DATAPATH / PKG_NAME, session_dir)
+
+    includes = [
+        'a different title',  # changed in custom index.rst
+        'basic_cpp_and_more',  # changed in custom config.py
+    ]
+    do_test_package(PKG_NAME, session_dir, includes=includes)
+
+    # Previously, running rosdoc2 would create a 'generated' folder in the doc
+    # subdirectory of the package. Directory refactoring should have eliminated
+    # this.
+    generated = pathlib.Path(DATAPATH / PKG_NAME / 'doc' / 'generated')
+    assert not generated.exists(), \
+        'Building should not create a "generated" directory in package/doc'