From eca80c6cd4e2c232ba95248c29ec219a87c6bc34 Mon Sep 17 00:00:00 2001 From: Jonas Otto Date: Fri, 16 Feb 2024 23:13:30 +0100 Subject: [PATCH 1/3] add more default configuration to sphinx conf.py Add values extracted from package.xml to the wrapping sphinx config.py. This eliminates the need for packages with custom config.py to duplicate author, copyright and version information from package.xml. --- rosdoc2/verbs/build/builders/sphinx_builder.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/rosdoc2/verbs/build/builders/sphinx_builder.py b/rosdoc2/verbs/build/builders/sphinx_builder.py index 579e332..fff77e1 100644 --- a/rosdoc2/verbs/build/builders/sphinx_builder.py +++ b/rosdoc2/verbs/build/builders/sphinx_builder.py @@ -72,6 +72,10 @@ def ensure_global(name, default): ensure_global('rosdoc2_settings', {{}}) ensure_global('extensions', []) +ensure_global('project', "{package_name}") +ensure_global('author', "{package_authors}") +ensure_global('release', "{package.version}") +ensure_global('version', "{package_version_short}") if rosdoc2_settings.get('enable_autodoc', True): print('[rosdoc2] enabling autodoc', file=sys.stderr) @@ -643,7 +647,12 @@ def generate_wrapping_rosdoc2_sphinx_project_into_directory( 'user_conf_py_filename': esc_backslash( os.path.abspath(os.path.join(user_sourcedir, 'conf.py'))), 'breathe_projects': ',\n'.join(breathe_projects) + '\n ', - 'intersphinx_mapping_extensions': ',\n '.join(intersphinx_mapping_extensions) + 'intersphinx_mapping_extensions': ',\n '.join(intersphinx_mapping_extensions), + 'package': package, + 'package_authors': ', '.join(set( + [a.name for a in package.authors] + [m.name for m in package.maintainers] + )), + 'package_version_short': '.'.join(package.version.split('.')[0:2]), } print(os.path.abspath(os.path.join(directory, 'conf.py'))) From 9585320d5076a3f708d8cfb016bbd192b077c156 Mon Sep 17 00:00:00 2001 From: Jonas Otto Date: Sat, 17 Feb 2024 13:16:15 +0100 Subject: [PATCH 2/3] add information about wrapping sphinx conf.py to README.md --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 873bd6a..10d5b77 100644 --- a/README.md +++ b/README.md @@ -158,6 +158,9 @@ The Sphinx builder will attempt to do a few things to ensure it runs even withou The final default is in place, even for packages with only C++, so that we can enable cross-referencing between packages using Sphinx and Breathe. +If an existing sphinx project is found, the `conf.py` sphinx configuration will be extended to enable rosdoc2-specific features according to the rosdoc2 configuration. +Additionally, the `project`, `author`, `release` and `version` options are populated from package.xml if they are not specified in `conf.py`. + #### Doxygen Builder The Doxygen builder will attempt to run even with no additional configuration, following these steps: From 3d7b2ea25eca0e400ed253fc231b4a2daa9803fb Mon Sep 17 00:00:00 2001 From: Jonas Otto Date: Sun, 25 Feb 2024 10:40:55 +0100 Subject: [PATCH 3/3] sort package authors Co-authored-by: Tully Foote --- rosdoc2/verbs/build/builders/sphinx_builder.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rosdoc2/verbs/build/builders/sphinx_builder.py b/rosdoc2/verbs/build/builders/sphinx_builder.py index fff77e1..64bb5b0 100644 --- a/rosdoc2/verbs/build/builders/sphinx_builder.py +++ b/rosdoc2/verbs/build/builders/sphinx_builder.py @@ -649,9 +649,9 @@ def generate_wrapping_rosdoc2_sphinx_project_into_directory( 'breathe_projects': ',\n'.join(breathe_projects) + '\n ', 'intersphinx_mapping_extensions': ',\n '.join(intersphinx_mapping_extensions), 'package': package, - 'package_authors': ', '.join(set( + 'package_authors': ', '.join(sorted(set( [a.name for a in package.authors] + [m.name for m in package.maintainers] - )), + ))), 'package_version_short': '.'.join(package.version.split('.')[0:2]), }