[PATCH 0/3] ci: don't compile whole project when testing docs with Meson

[PATCH 0/3] ci: don't compile whole project when testing docs with Meson

[Patrick Steinhardt]

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]: <aLCf0UaTxy5Nxpv/@szeder.dev>

---
Patrick Steinhardt (3):
      meson: introduce a "docs" alias to compile documentation only
      meson: print docs backend as part of the summary
      ci: don't compile whole project when testing docs with Meson

 Documentation/howto/meson.build     |  4 ++--
 Documentation/meson.build           |  8 ++++----
 Documentation/technical/meson.build |  4 ++--
 ci/test-documentation.sh            |  4 ++--
 contrib/contacts/meson.build        |  4 ++--
 contrib/subtree/meson.build         |  4 ++--
 meson.build                         | 10 ++++++++++
 7 files changed, 24 insertions(+), 14 deletions(-)


---
base-commit: ab427cd991100e94792fce124b0934135abdea4b
change-id: 20250911-b4-pks-meson-docs-target-56d8a21e84bf

[PATCH 1/3] meson: introduce a "docs" alias to compile documentation only

[Patrick Steinhardt]

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 <ps@pks.im>
---
 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 e34965c5b0..44f94cdb7b 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 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 b3dfcc0497..40b2a2dc54 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',

-- 
2.51.0.450.g87641ccf93.dirty

[PATCH 2/3] meson: print docs backend as part of the summary

[Patrick Steinhardt]

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 <ps@pks.im>
---
 meson.build | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/meson.build b/meson.build
index 40b2a2dc54..4a504fc26d 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,

-- 
2.51.0.450.g87641ccf93.dirty

[PATCH 3/3] ci: don't compile whole project when testing docs with Meson

[Patrick Steinhardt]

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 <szeder.dev@gmail.com>
Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 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
 

-- 
2.51.0.450.g87641ccf93.dirty

Re: [PATCH 0/3] ci: don't compile whole project when testing docs with Meson

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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].

There are three patches ;-).

The end-user facing get_option() is called "docs", unlike what the
"make" side understands, which is "make doc", even though internally
we call the target internally as "doc_targets" (not "docs_target").

I wonder if we want to let people say "meson compile doc" to match
the other world?

Will queue.  Thanks.

>
> Thanks!
>
> Patrick
>
> [1]: <aLCf0UaTxy5Nxpv/@szeder.dev>
>
> ---
> Patrick Steinhardt (3):
>       meson: introduce a "docs" alias to compile documentation only
>       meson: print docs backend as part of the summary
>       ci: don't compile whole project when testing docs with Meson
>
>  Documentation/howto/meson.build     |  4 ++--
>  Documentation/meson.build           |  8 ++++----
>  Documentation/technical/meson.build |  4 ++--
>  ci/test-documentation.sh            |  4 ++--
>  contrib/contacts/meson.build        |  4 ++--
>  contrib/subtree/meson.build         |  4 ++--
>  meson.build                         | 10 ++++++++++
>  7 files changed, 24 insertions(+), 14 deletions(-)
>
>
> ---
> base-commit: ab427cd991100e94792fce124b0934135abdea4b
> change-id: 20250911-b4-pks-meson-docs-target-56d8a21e84bf

Re: [PATCH 0/3] ci: don't compile whole project when testing docs with Meson

[Patrick Steinhardt]

On Thu, Sep 11, 2025 at 10:02:22AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > 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].
> 
> There are three patches ;-).

Oops, yeah. I added the summary patch close before sending this out :)

> The end-user facing get_option() is called "docs", unlike what the
> "make" side understands, which is "make doc", even though internally
> we call the target internally as "doc_targets" (not "docs_target").
> 
> I wonder if we want to let people say "meson compile doc" to match
> the other world?
> 
> Will queue.  Thanks.

The reason why I picked 'docs' is that the accompanying user-facing
option is also named the same way. It's thus a bit more consistent with
itself to call the target 'docs' as well.

So I slightly lean towards keeping 'docs', but I don't feel too strongly
about it.

Patrick

Re: [PATCH 0/3] ci: don't compile whole project when testing docs with Meson

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

>> I wonder if we want to let people say "meson compile doc" to match
>> the other world?
>> 
>> Will queue.  Thanks.
>
> The reason why I picked 'docs' is that the accompanying user-facing
> option is also named the same way. It's thus a bit more consistent with
> itself to call the target 'docs' as well.

Sorry, but I am not sure what user-facing "docs" option you are
referring to; is this some earlier mistake we made that is way too
entrenched to fix?  I do know about the "make docs" that barfs with
"*** No rule to make target 'docs'.  Stop.", and I would call it
user-facing.  I would say it is a bit too old to "correct" without
disrupting existing users.

Thanks.

Re: [PATCH 0/3] ci: don't compile whole project when testing docs with Meson

[Patrick Steinhardt]

On Mon, Sep 15, 2025 at 04:13:00PM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> >> I wonder if we want to let people say "meson compile doc" to match
> >> the other world?
> >> 
> >> Will queue.  Thanks.
> >
> > The reason why I picked 'docs' is that the accompanying user-facing
> > option is also named the same way. It's thus a bit more consistent with
> > itself to call the target 'docs' as well.
> 
> Sorry, but I am not sure what user-facing "docs" option you are
> referring to; is this some earlier mistake we made that is way too
> entrenched to fix?  I do know about the "make docs" that barfs with
> "*** No rule to make target 'docs'.  Stop.", and I would call it
> user-facing.  I would say it is a bit too old to "correct" without
> disrupting existing users.

I meant the Meson option `-Ddocs=man,html`. I feel it's more natural
there if the accompanying target is also called "docs" there.

Another option is that we could also just have both. In that case users
of the Makefile could continue to use the "doc" target with Meson, as
they are used to. And users that are used to Meson can use the "docs"
target.

Patrick

Re: [PATCH 1/3] meson: introduce a "docs" alias to compile documentation only

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 1258 bytes --]

Patrick Steinhardt <ps@pks.im> writes:

> 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`.
>

So earlier we would compile the documentation always (while the
dependencies are met). Now we move this to a "docs" subcommand...

[snip]

> diff --git a/meson.build b/meson.build
> index b3dfcc0497..40b2a2dc54 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
> +

Shouldn't we also add it to 'meson_options.txt' with default set to
true? That would ensure that `meson compile` would also build the docs.

>  exclude_from_check_headers = [
>    'compat/',
>    'unicode-width.h',
>
> --
> 2.51.0.450.g87641ccf93.dirty

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [PATCH 3/3] ci: don't compile whole project when testing docs with Meson

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 1742 bytes --]

Patrick Steinhardt <ps@pks.im> writes:

> 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 <szeder.dev@gmail.com>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
>  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
>
>

This makes sense. I really like how a lot of our CI config is forge
agnostic. I opened the patch expecting to review GitHub/GitLab changes.
Glad I didn't have to.

> --
> 2.51.0.450.g87641ccf93.dirty

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [PATCH 0/3] ci: don't compile whole project when testing docs with Meson

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 408 bytes --]

Patrick Steinhardt <ps@pks.im> writes:

> 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].
>

One small question from my side on the first patch, regarding the build
options. Looks good otherwise.

[snip]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [PATCH 1/3] meson: introduce a "docs" alias to compile documentation only

[Patrick Steinhardt]

On Tue, Sep 16, 2025 at 04:14:56AM -0500, Karthik Nayak wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> > diff --git a/meson.build b/meson.build
> > index b3dfcc0497..40b2a2dc54 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
> > +
> 
> Shouldn't we also add it to 'meson_options.txt' with default set to
> true? That would ensure that `meson compile` would also build the docs.

We already have the "docs" option in "meson_options.txt". In fact, it is
not even possible to have an option that is _not_ declared in that file
:)

The option accepts an array of choices, where the choices can be "man"
or "html" to build manpages, HTML sites, both or none. So as soon as the
user made at least one choice we enable the "docs" target automatically.

Patrick

Re: [PATCH 1/3] meson: introduce a "docs" alias to compile documentation only

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 1437 bytes --]

Patrick Steinhardt <ps@pks.im> writes:

> On Tue, Sep 16, 2025 at 04:14:56AM -0500, Karthik Nayak wrote:
>> Patrick Steinhardt <ps@pks.im> writes:
>> > diff --git a/meson.build b/meson.build
>> > index b3dfcc0497..40b2a2dc54 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
>> > +
>>
>> Shouldn't we also add it to 'meson_options.txt' with default set to
>> true? That would ensure that `meson compile` would also build the docs.
>
> We already have the "docs" option in "meson_options.txt". In fact, it is
> not even possible to have an option that is _not_ declared in that file
> :)
>

Nice. I should've verified, I was merely looking at the diff-stat

> The option accepts an array of choices, where the choices can be "man"
> or "html" to build manpages, HTML sites, both or none. So as soon as the
> user made at least one choice we enable the "docs" target automatically.
>

Okay that makes sense! The default is set to '[]'. Okay looks good.
Thanks for clarifying.

> Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [PATCH 0/3] ci: don't compile whole project when testing docs with Meson

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> I meant the Meson option `-Ddocs=man,html`. I feel it's more natural
> there if the accompanying target is also called "docs" there.

Ahh.  OK, so if I said "meson -Ddocs=" to choose neither format,
that would essentially be the same as "do build the binaries but not
the docs"?

I guess that is from the very beginning 904339ed (Introduce support
for the Meson build system, 2024-12-06) that get_option('docs') is
part of the build system, so it *is* way too late to fix it now.

> Another option is that we could also just have both. In that case users
> of the Makefile could continue to use the "doc" target with Meson, as
> they are used to. And users that are used to Meson can use the "docs"
> target.

Meaning you'd allow one to be an alias for the other?  I am not sure
if it is worth it for something small like this.  Let's leave things
as they are.

Thanks.