On Mon, Dec 23, 2024 at 12:51:54PM +0100, Toon Claes wrote:

Patrick Steinhardt [off-list ref] writes:

quoted

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