From f20dbe229aa8aefdb0369722130f3554434bfd8a Mon Sep 17 00:00:00 2001 From: "R. Kent James" Date: Thu, 15 Aug 2024 09:33:47 -0700 Subject: [PATCH 1/2] Add never_run_doxygen and never_run_sphinx_apidoc options Signed-off-by: R. Kent James ' or 'src/' build_context.python_source = settings_dict.get('python_source', None) build_context.always_run_doxygen = settings_dict.get('always_run_doxygen', False) + build_context.never_run_doxygen = settings_dict.get('never_run_doxygen', False) build_context.always_run_sphinx_apidoc = settings_dict.get('always_run_sphinx_apidoc', False) + build_context.never_run_sphinx_apidoc = settings_dict.get('never_run_sphinx_apidoc', False) build_context.build_type = settings_dict.get('override_build_type', build_context.build_type) builders = [] diff --git a/test/packages/default_yaml/rosdoc2.yaml b/test/packages/default_yaml/rosdoc2.yaml index 2dec477a..15b4f5b5 100644 --- a/test/packages/default_yaml/rosdoc2.yaml +++ b/test/packages/default_yaml/rosdoc2.yaml @@ -19,11 +19,22 @@ settings: { ## of the `ament_cmake/cmake` build type. always_run_doxygen: false, + ## This setting, if true, will skip running doxygen` and the `breathe`/`exhale` + ## extensions to `sphinx` regardless of build type. This is most useful if the + ## user has generated C++ documentation elsewhere that is included in the doc + ## folder, or in external documentation. + never_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 true, will skip running `sphinx-apidoc` regardless of build + ## type. This is most useful if the user has generated python documentation elsewhere + ## that is included in the doc folder, or in external documentation. + never_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. diff --git a/test/packages/never_doxygen/CMakeLists.txt b/test/packages/never_doxygen/CMakeLists.txt new file mode 100644 index 00000000..85e1d00c --- /dev/null +++ b/test/packages/never_doxygen/CMakeLists.txt @@ -0,0 +1,35 @@ +cmake_minimum_required(VERSION 3.8) +project(never_doxygen) + +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( REQUIRED) + +add_executable(test_node src/test_node.cpp) +target_include_directories(test_node PUBLIC + $ + $) +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() diff --git a/test/packages/never_doxygen/include/never_doxygen/test_node.hpp b/test/packages/never_doxygen/include/never_doxygen/test_node.hpp new file mode 100644 index 00000000..77308c2c --- /dev/null +++ b/test/packages/never_doxygen/include/never_doxygen/test_node.hpp @@ -0,0 +1,27 @@ +// +// Copyright 2024 R. Kent James +// +// 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 NEVER_DOXYGEN__TEST_NODE_HPP_ +#define NEVER_DOXYGEN__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 // NEVER_DOXYGEN__TEST_NODE_HPP_ diff --git a/test/packages/never_doxygen/package.xml b/test/packages/never_doxygen/package.xml new file mode 100644 index 00000000..8b642883 --- /dev/null +++ b/test/packages/never_doxygen/package.xml @@ -0,0 +1,19 @@ + + + + never_doxygen + 0.0.0 + Basic c++ package with never_run_doxygen set + ros2 user + Apache 2.0 + + ament_cmake + + ament_lint_auto + ament_lint_common + + + ament_cmake + rosdoc2.yaml + + diff --git a/test/packages/never_doxygen/rosdoc2.yaml b/test/packages/never_doxygen/rosdoc2.yaml new file mode 100644 index 00000000..af9d30b0 --- /dev/null +++ b/test/packages/never_doxygen/rosdoc2.yaml @@ -0,0 +1,18 @@ +## This 'attic section' self-documents this file's type and version. +type: 'rosdoc2 config' +version: 1 + +--- + +settings: { + ## This setting, if true, will skip running doxygen` and the `breathe`/`exhale` + ## extensions to `sphinx` regardless of build type. This is most useful if the + ## user has generated C++ documentation elsewhere that is included in the doc + ## folder, or in external documentation. + never_run_doxygen: true, +} +builders: + - doxygen: { + } + - sphinx: { + } diff --git a/test/packages/never_doxygen/src/test_node.cpp b/test/packages/never_doxygen/src/test_node.cpp new file mode 100644 index 00000000..7f7feb1b --- /dev/null +++ b/test/packages/never_doxygen/src/test_node.cpp @@ -0,0 +1,10 @@ +#include + +int main(int argc, char ** argv) +{ + (void) argc; + (void) argv; + + printf("hello world never_doxygen package\n"); + return 0; +} diff --git a/test/packages/never_sphinx_apidoc/README.txt b/test/packages/never_sphinx_apidoc/README.txt new file mode 100644 index 00000000..c405d7f6 --- /dev/null +++ b/test/packages/never_sphinx_apidoc/README.txt @@ -0,0 +1 @@ +This is a README as simple text. diff --git a/test/packages/never_sphinx_apidoc/never_sphinx_apidoc/__init__.py b/test/packages/never_sphinx_apidoc/never_sphinx_apidoc/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/test/packages/never_sphinx_apidoc/never_sphinx_apidoc/python_node.py b/test/packages/never_sphinx_apidoc/never_sphinx_apidoc/python_node.py new file mode 100644 index 00000000..37e7dc2f --- /dev/null +++ b/test/packages/never_sphinx_apidoc/never_sphinx_apidoc/python_node.py @@ -0,0 +1,6 @@ +def main(): + print('Hi from never_sphinx_apidoc.') + + +if __name__ == '__main__': + main() diff --git a/test/packages/never_sphinx_apidoc/package.xml b/test/packages/never_sphinx_apidoc/package.xml new file mode 100644 index 00000000..9ded4acf --- /dev/null +++ b/test/packages/never_sphinx_apidoc/package.xml @@ -0,0 +1,19 @@ + + + + never_sphinx_apidoc + 0.0.0 + Python but sphinx api disabled + Ye ol' Python Pro + Apache-2.0 + + ament_copyright + ament_flake8 + ament_pep257 + python3-pytest + + + ament_python + rosdoc2.yaml + + diff --git a/test/packages/never_sphinx_apidoc/rosdoc2.yaml b/test/packages/never_sphinx_apidoc/rosdoc2.yaml new file mode 100644 index 00000000..584594f5 --- /dev/null +++ b/test/packages/never_sphinx_apidoc/rosdoc2.yaml @@ -0,0 +1,17 @@ +## This 'attic section' self-documents this file's type and version. +type: 'rosdoc2 config' +version: 1 + +--- + +settings: { + ## This setting, if true, will skip running `sphinx-apidoc` regardless of build + ## type. This is most useful if the user has generated python documentation elsewhere + ## that is included in the doc folder, or in external documentation. + never_run_sphinx_apidoc: true, +} +builders: + - doxygen: { + } + - sphinx: { + } diff --git a/test/packages/never_sphinx_apidoc/setup.cfg b/test/packages/never_sphinx_apidoc/setup.cfg new file mode 100644 index 00000000..da83911e --- /dev/null +++ b/test/packages/never_sphinx_apidoc/setup.cfg @@ -0,0 +1,4 @@ +[develop] +script_dir=$base/lib/never_sphinx_apidoc +[install] +install_scripts=$base/lib/never_sphinx_apidoc diff --git a/test/packages/never_sphinx_apidoc/setup.py b/test/packages/never_sphinx_apidoc/setup.py new file mode 100644 index 00000000..553843cf --- /dev/null +++ b/test/packages/never_sphinx_apidoc/setup.py @@ -0,0 +1,26 @@ +from setuptools import find_packages, setup + +package_name = 'never_sphinx_apidoc' + +setup( + name=package_name, + version='0.0.0', + packages=find_packages(exclude=['test']), + data_files=[ + ('share/ament_index/resource_index/packages', + ['resource/' + package_name]), + ('share/' + package_name, ['package.xml']), + ], + install_requires=['setuptools'], + zip_safe=True, + maintainer='kent', + maintainer_email='kent@caspia.com', + description='TODO: Package description', + license='TODO: License declaration', + tests_require=['pytest'], + entry_points={ + 'console_scripts': [ + 'python_node = never_sphinx_apidoc.python_node:main' + ], + }, +) diff --git a/test/test_builder.py b/test/test_builder.py index 0047cf52..b518cd63 100644 --- a/test/test_builder.py +++ b/test/test_builder.py @@ -57,6 +57,36 @@ def do_build_package(package_path, work_path, with_extension=False) -> None: main_impl(options) +def test_never_sphinx_apidoc(module_dir): + """Tests of never_run_sphinx_apidoc.""" + PKG_NAME = 'never_sphinx_apidoc' + do_build_package(DATAPATH / PKG_NAME, module_dir) + + includes = [ + PKG_NAME, + ] + + excludes = ['python api'] # No python api generated since never_run_sphinx_apidoc is set + + do_test_package(PKG_NAME, module_dir, + includes=includes, excludes=excludes) + + +def test_never_doxygen(module_dir): + """Tests of never_run_doxygen.""" + PKG_NAME = 'never_doxygen' + do_build_package(DATAPATH / PKG_NAME, module_dir) + + includes = [ + PKG_NAME, + ] + + excludes = ['c++ api'] # No c++ api since never_run_doxygen set + + do_test_package(PKG_NAME, module_dir, + includes=includes, excludes=excludes) + + def test_minimum_package(module_dir): """Tests of a package containing as little as possible.""" PKG_NAME = 'minimum_package' From 9ee86a53402193d33fdb8d862b1b58072576fb37 Mon Sep 17 00:00:00 2001 From: "R. Kent James" Date: Wed, 20 Nov 2024 16:27:03 -0800 Subject: [PATCH 2/2] Improve warning messages for never_run sphinx and doxygen Signed-off-by: R. Kent James --- rosdoc2/verbs/build/builders/doxygen_builder.py | 2 +- rosdoc2/verbs/build/builders/sphinx_builder.py | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/rosdoc2/verbs/build/builders/doxygen_builder.py b/rosdoc2/verbs/build/builders/doxygen_builder.py index b488ece8..1553bc12 100644 --- a/rosdoc2/verbs/build/builders/doxygen_builder.py +++ b/rosdoc2/verbs/build/builders/doxygen_builder.py @@ -182,7 +182,7 @@ def build(self, *, doc_build_folder, output_staging_directory): return None # Explicitly generated no documentation. if self.build_context.never_run_doxygen: - logger.debug('The package has never_run_doxygen set, so skipping doxygen.') + logger.info('The package has never_run_doxygen set, so skipping doxygen.') return None # If both doxyfile and doxyfile_content are None, that means there is diff --git a/rosdoc2/verbs/build/builders/sphinx_builder.py b/rosdoc2/verbs/build/builders/sphinx_builder.py index fff84b26..4188170a 100644 --- a/rosdoc2/verbs/build/builders/sphinx_builder.py +++ b/rosdoc2/verbs/build/builders/sphinx_builder.py @@ -542,6 +542,9 @@ def build(self, *, doc_build_folder, output_staging_directory): ] build_context = self.build_context + if build_context.never_run_sphinx_apidoc: + logger.info( + 'The package has never_run_sphinx_apidoc set, so sphinx apidoc will not be run.') has_python = ( build_context.build_type == 'ament_python' or build_context.always_run_sphinx_apidoc