meson: build docs with meson

[jelly]

Introduce a custom target build-docs to build the sphinx documentation.

[jelly]

This needs some discussion, do you want a custom target or always build documentation when -Ddocs=true is provided. Either way this seems doable with meson :)

[jelly]

Also FYI, make docs is completely broken now on main:

[jelle@toolbx python-systemd]$ make doc python -m pip install . Defaulting to user installation because normal site-packages is not writeable Processing /home/jelle/projects/python-systemd Installing build dependencies ... done Getting requirements to build wheel ... done Preparing metadata (pyproject.toml) ... done Building wheels for collected packages: systemd-python Building wheel for systemd-python (pyproject.toml) ... done Created wheel for systemd-python: filename=systemd_python-236-cp314-cp314-linux_x86_64.whl size=63848 sha256=042914319b6d0c6d37a15c31ae874ffb62f1c1ddcc2a2942408414a5d052ecca Stored in directory: /home/jelle/.cache/pip/wheels/b1/7f/f3/6282dd246c3a670ea95ce507e7d60676a0fbcc7c59e332c369 Successfully built systemd-python Installing collected packages: systemd-python Attempting uninstall: systemd-python Found existing installation: systemd-python 236 Uninstalling systemd-python-236: Successfully uninstalled systemd-python-236 Successfully installed systemd-python-236 mkdir build && cd build && python -m sphinx -b html -D version=236 -D release=236 ../docs html mkdir: cannot create directory ‘build’: File exists make: *** [Makefile:48: sphinx-html] Error 1 

[keszybz]

Can we make it so that it is built by default and installed if docs is true? It's nice if the target is always defined, because then it makes development easier, because one can rebuild the docs on demand but it doesn't interfere with normal development.

[keszybz]

Oh, and let's call the target docs…

[jelly]

Right, so this was mostly me learning a bit more of meson and I was leaning on two ideas:

• For packaging you probably want a -Ddocs=true option (so this also needs an install target)
• For development you could get away with just meson -C build build-docs

I'm happy to make this a docs target and default to true, probably should also add an install target then.

However the main blocker for this is building the docs that they need to import systemd and that can't be done from a checkout even with setting PYTHONPATH=build/src. @behrmann was working on moving the tests to a meson target with a virtualenv and an editable install so that would need to be finished first.

[keszybz]

→ #161

[jelly]

→ #161

Hah! Was hacking towards the same objective yesterday night and that led to the same success with PYTHONPATH=build/src pytest test. So not having to copy the tests around.

[keszybz]

On Sun, Oct 12, 2025 at 05:41:14AM -0700, Jelle van der Waa wrote: I'm happy to make this a `docs` target and default to true, probably should also add an install target then.

Meson has 'install tags'. We could add that, but I think that might be overkill. I think there are two main scenarios: - to build docs for development or local use: for that, 'ninja -C build docs' is the answer. - to build docs as part of a package build and installation. For that, setting a config option and then just having everything happen as part of the main build and install works best.

However the main blocker for this is building the docs that they need to import `systemd` and that can't be done from a checkout even with setting `PYTHONPATH=build/src`. @behrmann was working on moving the tests to a `meson` target with a virtualenv and an editable install so that would need to be finished first.

Yeah, the current state is fairly annoying. I think it'd be nice to just copy the .py files to the build directory and import the module from there. Maybe some sort of enhancement to meson-python would be possible.

[jelly]

On Sun, Oct 12, 2025 at 05:41:14AM -0700, Jelle van der Waa wrote: I'm happy to make this a docs target and default to true, probably should also add an install target then.
Meson has 'install tags'. We could add that, but I think that might be overkill. I think there are two main scenarios: - to build docs for development or local use: for that, 'ninja -C build docs' is the answer. - to build docs as part of a package build and installation. For that, setting a config option and then just having everything happen as part of the main build and install works best.
However the main blocker for this is building the docs that they need to import systemd and that can't be done from a checkout even with setting PYTHONPATH=build/src. @behrmann was working on moving the tests to a meson target with a virtualenv and an editable install so that would need to be finished first.
Yeah, the current state is fairly annoying. I think it'd be nice to just copy the .py files to the build directory and import the module from there. Maybe some sort of enhancement to meson-python would be possible.

We tried copying over the .py files but that wasn't enough. I should do a proper write up why that didn't work.

[keszybz]

Please rebase on top of #161 which was just merged.

[jelly]

I wonder if I should remove the -Ddocs=true option as it wouldn't be too useful for packaging as data files are not supported by meson-python.

Another thing I wonder about if you want me to move this to docs/meson.build.

[keszybz]

I wonder if I should remove the -Ddocs=true option as it wouldn't be too useful for packaging as data files are not supported by meson-python.

I think this doesn't matter. Packaging can just list the docs separately.

Another thing I wonder about if you want me to move this to docs/meson.build.

I think it's fine right now. It's just a few lines anyway…

---

I get the following: docs is not a known target. ninja knows html target. Maybe html is actually a better name, since we might want to allow further doc types in the future, e.g. man pages. But then the README needs to be updated to say "html".

[keszybz]

LGTM, thanks.