From 2c2cae0fe723d1a2923727f023a802504488f21f Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Thu, 11 Sep 2025 09:39:04 +0200 Subject: [PATCH 1/4] ci: don't compile whole project when testing docs with Meson MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hi, these two patches introduce a new "docs" alias into Meson and use it in our "documentation" CI jobs so that we stop compiling all of Git only to verify the generated manpages. This fixes the issue reported by Gábor in [1]. Thanks! Patrick [1]: To: git@vger.kernel.org Cc: SZEDER Gábor --- b4-submit-tracking --- # This section is used internally by b4 prep for tracking purposes. { "series": { "revision": 1, "change-id": "20250911-b4-pks-meson-docs-target-56d8a21e84bf", "prefixes": [] } } -- GitLab From 108ce1e8e586b8ba9bf471f9ff62f683ed6c2a62 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Thu, 11 Sep 2025 09:37:17 +0200 Subject: [PATCH 2/4] meson: introduce a "docs" alias to compile documentation only Meson does not currently provide a target to compile documentation, only. Instead, users needs to compile the whole project, which may be way more than they really intend to do. Introduce a new "docs" alias to plug this gap. This alias can be invoked e.g. with `meson compile docs`. Signed-off-by: Patrick Steinhardt --- Documentation/howto/meson.build | 4 ++-- Documentation/meson.build | 8 ++++---- Documentation/technical/meson.build | 4 ++-- contrib/contacts/meson.build | 4 ++-- contrib/subtree/meson.build | 4 ++-- meson.build | 7 +++++++ 6 files changed, 19 insertions(+), 12 deletions(-) diff --git a/Documentation/howto/meson.build b/Documentation/howto/meson.build index 81000028c08..ece20244af2 100644 --- a/Documentation/howto/meson.build +++ b/Documentation/howto/meson.build @@ -29,7 +29,7 @@ howto_index = custom_target( output: 'howto-index.adoc', ) -custom_target( +doc_targets += custom_target( command: asciidoc_html_options, input: howto_index, output: 'howto-index.html', @@ -51,7 +51,7 @@ foreach howto : howto_sources capture: true, ) - custom_target( + doc_targets += custom_target( command: asciidoc_html_options, input: howto_stripped, output: fs.stem(howto_stripped.full_path()) + '.html', diff --git a/Documentation/meson.build b/Documentation/meson.build index e34965c5b0e..44f94cdb7ba 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -377,7 +377,7 @@ foreach manpage, category : manpages output: fs.stem(manpage) + '.xml', ) - custom_target( + doc_targets += custom_target( command: [ xmlto, '-m', '@INPUT0@', @@ -400,7 +400,7 @@ foreach manpage, category : manpages endif if get_option('docs').contains('html') - custom_target( + doc_targets += custom_target( command: asciidoc_common_options + [ '--backend=' + asciidoc_html, '--doctype=manpage', @@ -452,7 +452,7 @@ if get_option('docs').contains('html') depends: documentation_deps, ) - custom_target( + doc_targets += custom_target( command: [ xsltproc, '--xinclude', @@ -481,7 +481,7 @@ if get_option('docs').contains('html') ] foreach article : articles - custom_target( + doc_targets += custom_target( command: asciidoc_common_options + [ '--backend=' + asciidoc_html, '--out-file=@OUTPUT@', diff --git a/Documentation/technical/meson.build b/Documentation/technical/meson.build index a13aafcfbb8..858af811a7b 100644 --- a/Documentation/technical/meson.build +++ b/Documentation/technical/meson.build @@ -46,7 +46,7 @@ api_index = custom_target( output: 'api-index.adoc', ) -custom_target( +doc_targets += custom_target( command: asciidoc_html_options, input: api_index, output: 'api-index.html', @@ -56,7 +56,7 @@ custom_target( ) foreach article : api_docs + articles - custom_target( + doc_targets += custom_target( command: asciidoc_html_options, input: article, output: fs.stem(article) + '.html', diff --git a/contrib/contacts/meson.build b/contrib/contacts/meson.build index 73d82dfe52b..c8fdb35ed99 100644 --- a/contrib/contacts/meson.build +++ b/contrib/contacts/meson.build @@ -20,7 +20,7 @@ if get_option('docs').contains('man') output: 'git-contacts.xml', ) - custom_target( + doc_targets += custom_target( command: [ xmlto, '-m', '@INPUT@', @@ -39,7 +39,7 @@ if get_option('docs').contains('man') endif if get_option('docs').contains('html') - custom_target( + doc_targets += custom_target( command: asciidoc_common_options + [ '--backend=' + asciidoc_html, '--doctype=manpage', diff --git a/contrib/subtree/meson.build b/contrib/subtree/meson.build index 98dd8e0c8ea..46cdbcc30c9 100644 --- a/contrib/subtree/meson.build +++ b/contrib/subtree/meson.build @@ -38,7 +38,7 @@ if get_option('docs').contains('man') output: 'git-subtree.xml', ) - custom_target( + doc_targets += custom_target( command: [ xmlto, '-m', '@INPUT@', @@ -57,7 +57,7 @@ if get_option('docs').contains('man') endif if get_option('docs').contains('html') - custom_target( + doc_targets += custom_target( command: asciidoc_common_options + [ '--backend=' + asciidoc_html, '--doctype=manpage', diff --git a/meson.build b/meson.build index b3dfcc04972..40b2a2dc548 100644 --- a/meson.build +++ b/meson.build @@ -2101,11 +2101,18 @@ endif subdir('bin-wrappers') if get_option('docs') != [] + doc_targets = [] subdir('Documentation') endif subdir('contrib') +# Note that the target is intentionally configured after including the +# 'contrib' directory, as some tool there also have their own manpages. +if get_option('docs') != [] + alias_target('docs', doc_targets) +endif + exclude_from_check_headers = [ 'compat/', 'unicode-width.h', -- GitLab From bbe5090f4bec7ed12767a8d01c2dec942669bcb8 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Thu, 11 Sep 2025 10:19:13 +0200 Subject: [PATCH 3/4] meson: print docs backend as part of the summary Our documentation can be built with either Asciidoc or Asciidoctor as backend. When Meson is configured to build documentation, then it will automatically detect which of these tools is available and use them. It's not obvious to the user though which of these backends is used unless the user explicitly asks for one backend via `-Ddocs_backend=`. Improve the status quo by printing the docs backend as part of the "backends" summary. Signed-off-by: Patrick Steinhardt --- meson.build | 3 +++ 1 file changed, 3 insertions(+) diff --git a/meson.build b/meson.build index 40b2a2dc548..4a504fc26d7 100644 --- a/meson.build +++ b/meson.build @@ -2103,6 +2103,8 @@ subdir('bin-wrappers') if get_option('docs') != [] doc_targets = [] subdir('Documentation') +else + docs_backend = 'none' endif subdir('contrib') @@ -2251,6 +2253,7 @@ summary({ summary({ 'csprng': csprng_backend, + 'docs': docs_backend, 'https': https_backend, 'sha1': sha1_backend, 'sha1_unsafe': sha1_unsafe_backend, -- GitLab From 09a341eaea765f83ef78db31b8ec4075ab756aa4 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Thu, 11 Sep 2025 09:37:44 +0200 Subject: [PATCH 4/4] ci: don't compile whole project when testing docs with Meson MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Our "documentation" CI jobs, unsurprisingly, performs a couple of tests on our documentation. The job knows to not only test the documentation generated by our Makefile, but also by Meson. In the latter case with Meson we end up building the whole project, including all of the binaries. This is of course quite excessive and a waste of compute cycles, as we don't care about these binaries at all. Fix this by using the new "docs" target that we introduced in the preceding commit. Reported-by: SZEDER Gábor Signed-off-by: Patrick Steinhardt --- ci/test-documentation.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh index 49f87f50fd7..5e4fd8fbd7a 100755 --- a/ci/test-documentation.sh +++ b/ci/test-documentation.sh @@ -48,13 +48,13 @@ check_unignored_build_artifacts # Build docs with Meson and AsciiDoc meson setup build-asciidoc -Ddocs=html,man -Ddocs_backend=asciidoc -meson compile -C build-asciidoc +meson compile -C build-asciidoc docs check_docs build-asciidoc AsciiDoc rm -rf build-asciidoc # Build docs with Meson and AsciiDoctor meson setup build-asciidoctor -Ddocs=html,man -Ddocs_backend=asciidoctor -meson compile -C build-asciidoctor +meson compile -C build-asciidoctor docs check_docs build-asciidoctor Asciidoctor rm -rf build-asciidoctor -- GitLab