From 197f0d0f390ef2f1e573a57c27ed7db8df7a46fd Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Thu, 11 Sep 2025 11:16:06 +0200 Subject: [PATCH 1/3] 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 Signed-off-by: Junio C Hamano --- 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 81000028c0..ece20244af 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 4404c623f0..f0169fcf9c 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -375,7 +375,7 @@ foreach manpage, category : manpages output: fs.stem(manpage) + '.xml', ) - custom_target( + doc_targets += custom_target( command: [ xmlto, '-m', '@INPUT0@', @@ -398,7 +398,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', @@ -450,7 +450,7 @@ if get_option('docs').contains('html') depends: documentation_deps, ) - custom_target( + doc_targets += custom_target( command: [ xsltproc, '--xinclude', @@ -479,7 +479,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 a13aafcfbb..858af811a7 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 73d82dfe52..c8fdb35ed9 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 98dd8e0c8e..46cdbcc30c 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 5dd299b496..f7dd6ee30d 100644 --- a/meson.build +++ b/meson.build @@ -2099,11 +2099,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', From b64579dff989f36343bdbb3e1d6481ee4a3f0876 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Thu, 11 Sep 2025 11:16:07 +0200 Subject: [PATCH 2/3] 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 Signed-off-by: Junio C Hamano --- meson.build | 3 +++ 1 file changed, 3 insertions(+) diff --git a/meson.build b/meson.build index f7dd6ee30d..cfaae83488 100644 --- a/meson.build +++ b/meson.build @@ -2101,6 +2101,8 @@ subdir('bin-wrappers') if get_option('docs') != [] doc_targets = [] subdir('Documentation') +else + docs_backend = 'none' endif subdir('contrib') @@ -2249,6 +2251,7 @@ summary({ summary({ 'csprng': csprng_backend, + 'docs': docs_backend, 'https': https_backend, 'sha1': sha1_backend, 'sha1_unsafe': sha1_unsafe_backend, From ff4ec8ded0504cbe4fb4705ad793d862acfc63fc Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Thu, 11 Sep 2025 11:16:08 +0200 Subject: [PATCH 3/3] 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 Signed-off-by: Junio C Hamano --- 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 49f87f50fd..5e4fd8fbd7 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