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