patch, 3 partsci: don't compile whole project when testing docs with Meson

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

> 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

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

> 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
> :)
>

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

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

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

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

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

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