gnome.gtkdoc(): Pass --html-dir to fixxref

[jtojnar]

Without this, on systems like Nix or Guix that install packages into their own prefixes, gtk-doc will not be able to correctly cross-reference the symbols.

Being passed --html-dir is expected by fixxref as per the comment:

https://gitlab.gnome.org/GNOME/gtk-doc/blob/250a21f24365b6fed6271b5f235307d9fbef5eeb/gtkdoc/fixxref.py#L60

and the Autotools macros indeed do that:

https://gitlab.gnome.org/GNOME/gtk-doc/blob/250a21f24365b6fed6271b5f235307d9fbef5eeb/buildsystems/autotools/gtk-doc.m4#L59-64
https://gitlab.gnome.org/GNOME/gtk-doc/-/blob/250a21f24365b6fed6271b5f235307d9fbef5eeb/buildsystems/autotools/gtk-doc.make#L217

[jtojnar]

Another issue is that Meson hardcodes ${prefix}/share, instead of ${datadir} and does not allow overriding the html_dir for packagers like Autotools do:

https://gitlab.gnome.org/GNOME/gtk-doc/blob/250a21f24365b6fed6271b5f235307d9fbef5eeb/buildsystems/autotools/gtk-doc.m4#L60-62

I can handle it here as well if this is something we want to support.

[jpakkane]

I have very little experience with gtk-doc, so I can't comment on the merits of this MR. Ping for any gtk-doc users.

does not allow overriding the html_dir for packagers like Autotools do

Is this something that people actually need and use? We have not had any bug reports about this (that I remember, anyway). In Meson we try not to add functionality and toggle options "just in case" but only when people have real world use cases.

[jtojnar]

Is this something that people actually need and use? We have not had any bug reports about this (that I remember, anyway).

On NixOS we install documentation into a different prefix. Currently we move it manually after installation but having an option for it would be nice. We can make do without it for now. (That reminds me, I have been meaning to re-open #2561 for a long time.)

In the future I want to work on gtk-doc documentation dependency resolution which would need to be aware of the moves but I guess we can add the option then.

[ebassi]

Well-behaved projects pass --html-dir to fixxref_args manually, e.g.:

• GLib
• GTK

mostly because they already need to override --extra-dir for every dependency's prefix. The main problem is that there aren't proper best practices for gtk-doc and Meson, so people either cargo-cult well-known projects, or miss out on things they ought to do.

[jtojnar]

Actually, reading the glib example, it should be just prefix and datadir. Will fix that.

[jtojnar]

Now I remember why I passed the full path instead of just the path to the html directory. It becomes problematic when a project passes a weird absolute install_dir to gnome.gtkdoc (though maybe we can hope no one does this?)

[jtojnar]

I guess that is one benefit of string concatenation https://gitlab.gnome.org/GNOME/gtk-doc/-/blob/250a21f24365b6fed6271b5f235307d9fbef5eeb/buildsystems/autotools/gtk-doc.make#L42, it does not allow projects to install docs to weird locations, making it completely up to distros.

I guess it is too late for disallowing passing absolute values not under ${datadir}/share/gtk-doc/html to install_dir?

[jtojnar]

Well-behaved projects pass --html-dir to fixxref_args manually, e.g.:

Yeah, I was hoping that having Meson do this automatically like Autotools did would make it a little easier to be well-behaved.

mostly because they already need to override --extra-dir for every dependency's prefix. The main problem is that there aren't proper best practices for gtk-doc and Meson, so people either cargo-cult well-known projects, or miss out on things they ought to do.

Yeah, this has annoyed me too. Especially since on NixOS everything is in its own prefix and you cannot easily determine the corresponding prefixes at run-time (unless you use pkg-config but that does not record gtkdoc paths):

$ nix-build -A glib.all
/nix/store/3r31y6q0758ydawww6nxdhrf34b85rdi-glib-2.64.1-bin
/nix/store/idqwnnq6a1mzci2fi2rc26wqz9s0aa4a-glib-2.64.1
/nix/store/4kjbn4854nsj9wx54a3pqmkdswy2w21c-glib-2.64.1-dev
/nix/store/pw0n8wcr547vqh57ax5ps4a6lz9831ms-glib-2.64.1-devdoc
/nix/store/y1dzq1h9nwgyzhmm318370lw79m9rwc3-glib-2.64.1-debug
$ nix-build -A gtk3.all
/nix/store/2chzii7gwmlcii9x73l0v3bl7lf2awvb-gtk+3-3.24.14
/nix/store/i325zwsijdfpsybcj5s4d1kz7ni2azc7-gtk+3-3.24.14-dev
/nix/store/sb8jg07h2fmv2ma4r8vz70si7vvl0rcf-gtk+3-3.24.14-devdoc
/nix/store/jmkq49hqh41c9a8ml9llq1qf5hd7qjb6-gtk+3-3.24.14-debug

I was thinking of various solutions:

• adding gtkdocdir to .pc files
• making gtk-doc search all subdirectories under $XDG_DATA_DIRS/gtk-doc/html (would be problematic on impure systems)
• introducing --pkg arguments to gtk-doc (similar to Vala’s --pkg), which would then make gtk-doc search $XDG_DATA_DIRS/gtk-doc/html/$pkg (like it does with $XDG_DATA_DIRS/vapi).
• making gtk-doc search all subdirectories under $GTK_DOC_PATH (cleaner since we could just set it during build)

I like the last two the most but I am not sure how receptive gtk-doc would be to support them.

[nielsdg]

* [](https://gitlab.gnome.org/GNOME/gtk/-/blob/master/docs/reference/gtk/meson.build#L425-433)

mostly because they already need to override --extra-dir for every dependency's prefix. The main problem is that there aren't proper best practices for gtk-doc and Meson, so people either cargo-cult well-known projects, or miss out on things they ought to do.

TIL. I guess this is something we should add to the docs?

[jpakkane]

Probably the best way to tackle this is for gtk-doc users/devs to come up with how they would want Meson to behave here (given all the best practices etc) and then we'd change our implementation to do that. I don't have that much usage experience with it so I don't have a good grasp on what it should do.