Re: [PATCH 00/10] meson: wire up missing HTML documentation

[Patrick Steinhardt <ps@pks.im>]

On Mon, Dec 23, 2024 at 12:51:54PM +0100, Toon Claes wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > Hi,
> >
> > this patch series wires up missing HTML-based documentation with Meson.
> > This includes a couple of missing manpages, the user manual as well as
> > the random set of articles that we have. It also starts to generate the
> > indices for API docs and howtos so that the result is a complete set of
> > HTML docs, same as with our Makefile. It also fixes a couple of smaller
> > issues I found while working on the series.
> >
> > Notably missing yet is an integration with CI as well as sanity checks
> > for any kind of missing docs in Meson. I'll work on this in a separate
> > patch series once the initial CI integration as well as this patch
> > series here have landed.
> >
> > Further missing is the generation of both info pages and a user manual
> > PDF. I couldn't find any users of these anywhere in downstream distros,
> > so I decided to not care for now until somebody complains.
> >
> > The series is built on top of caacdb5dfd (The fifteenth batch,
> > 2024-12-10) with ps/build at 904339edbd (Introduce support for the Meson
> > build system, 2024-12-06) merged into it.
> 
> Hi Patrick,
> 
> I've been reading through the patches, and as far as I understand it
> makes sense. But to be honest, I don't know how to use this. I have
> almost no experience with Meson and I only know `meson setup` and `meson
> compile`. But the `meson.build` from Documentation/ is marked as a
> subdir() if option "docs" is given. But I don't understand how this
> should be used. For `meson test` there are some instructions in the
> root-level meson.build, but not for the docs. Should we add this as
> well?

I don't really think it makes sense to explicitly point out every option
that we have. We already document how to discover and set options, and
from hereon it follows that you can wire up docs by running for example
`meson setup -Ddocs=man ..`. It's just another option, and as such it
can be discovered by running `meson configure`.

The benefit of this is that it cannot grow stale like the build options
in our Makefile. These may or may not have documentation, and may or may
not be stale. With Meson, every build option is listed explicitly, has
documentation and is discoverable via `meson configure`.

> And a bit related to this, I saw you use `env: script_environment` in a
> few places, how does this get injected from the root-level meson.build
> file? Due to this, I assume it's intended to only use the root-level
> meson.build directly, and not run `meson setup` in the Documentation/
> folder?

Yup, you are always expected to set up the top-level source directory,
not any of the subdirectories. The build instructions are then processed
linearly in Meson, so variables declared before a call to `subdir()`
would be accessible in the subdirectory, as well.

Patrick