gnome module: add global option to choose when to build gtkdoc HTML docs

[eli-schwartz]

It is fairly common for projects to want to make installation of HTML docs optionkal. Many projects have custom options that use

if get_option('something')
    indented_gtkdoc_invocation
endif

which is messy, hard to read, and above all else, inconsistent with different names for each project. Known options include

• gtk_doc
• gtk-doc
• doc
• docs

and possibly more. This is especially problematic for yielding options to a superproject, which is an exercise in frustration when it turns out each project has a different name.

Solve all these problems by resolving the option in the module itself.

This uses the new module options infrastructure, so the option name is backwards compatible. Any existing uses of get_option will simply add an extra layer of checks, but not break the option namespace.

FIXME: linkify ticket references

Fixes #1811 Fixes #8315

Related: #7444

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 40.00000% with 9 lines in your changes missing coverage. Please review.

Project coverage is 67.11%. Comparing base (6be2581) to head (f66182d). Report is 2857 commits behind head on master.

Files	Patch %	Lines
mesonbuild/modules/gnome.py	40.00%	6 Missing and 3 partials :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #9669      +/-   ##
==========================================
- Coverage   67.12%   67.11%   -0.02%     
==========================================
  Files         404      404              
  Lines       85767    85795      +28     
  Branches    18917    18923       +6     
==========================================
+ Hits        57572    57581       +9     
- Misses      23665    23678      +13     
- Partials     4530     4536       +6     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[xclaesse]

Makes a lot of sense, yes.

I'm a bit unsure about returning Disabler object thought, all other APIs return not-found object and have an explicit disabler: true kwarg. But I agree it does not really match this case neither... I think it's fine as you did, because it is extremely rare to use the return value of gtkdoc() method, and in practice it's only useful as order dependency when building other docs which would be disabled too anyway. Maybe make it more explicit in meson doc that it returns a disabler object?

Ideally, but not blocker for this PR, we should also have a migration plan for projects that have gtk_doc option already. We already have a mechanism for deprecating project options, we should extend it for example with option('gtk_doc', deprecated_for: 'gnome.gtkdoc'). Some project have a boolean for that option so we could have to even support that syntax: option('gtk_doc', deprecated_for: 'gnome.gtkdoc', deprecated: {'true': 'enabled', 'false': 'disabled'}).

[nielsdg]

I don't know how this impacts this PR, but I know some GNOME modules (like GTK) have migrated to gi-docgen, but have reused the gtk_doc name of the option to just build docs.

Example in GTK: https://gitlab.gnome.org/GNOME/gtk/-/blob/main/docs/reference/meson.build#L4

[eli-schwartz]

@nielsdg on that note... is gi-docgen something that the gnome community wants to add to meson's gnome module?

Either way it will remain trivial to do:

-build_docs = get_option('gtk_doc')
+build_docs = get_option('gnome.gtkdoc')

Assuming one bumps the minimum version of meson to require that builtin option.

[nielsdg]

@nielsdg on that note... is gi-docgen something that the gnome community wants to add to meson's gnome module?

No idea. Currently it works well enough for me with just a custom_target(), but it might be good to ask someonel like @ebassi .

About the change of option name: I'm going to ping the GNOME release team on this to get their feedback, since they would be impacted the first (and most) on such a change. Personally, I don't really care for a global option for building gtkdoc

[matthiasclasen]

I'm a member of a the release team, but this is just my personal opinion: I don't like this option sharing business (I guess I'm just not a fan of submodules in general).

[ebassi]

No idea. Currently it works well enough for me with just a custom_target(), but it might be good to ask someonel like @ebassi .

I was toying with the idea of writing a gnome.gidocgen(), but to be honest I haven't had time.

Changing the name of the option is exceedingly annoying, and in any case the update to Meson will be staggered across multiple releases, because not everyone depends on the bleeding edge version of Meson. The only problem is if we bump up the version of Meson in the GNOME SDK and we suddenly start getting warnings/errors on projects using option('gtk_doc').

[eli-schwartz]

My understanding is that currently the name of the option is already inconsistent across a number of different naming conventions. And as I mentioned earlier, the two options (builtin and project) can coexist. So adding the option and having projects which still use the old per-project option won't be of detriment to the GNOME SDK (or anyone else).

[nielsdg]

I think the problem is that this PR is too late for being useful:

• most projects have either already been ported to gtkdoc (with their own name for the specific option). If they change it again, they'll end up with yet another change that needs to be propagated through several builds systems (like jhbuild, gnome-build-meta, and every Meson project that uses it as a subproject, or builds as a git submodule)
• Some projects are already switching away from gtk-doc to gi-docgen, at which point they probably lose the gtkdoc option, or don't want to change it all, given the previous point

[mcatanzaro]

Thinking out loud, and I know I contradict what I said previously, but wondering if we should instead of have generic built-in option doc that can be used by hotdoc and gi-docgen too. Projects could also use it with their custom doxygen targets for example. It could cause issues with projects that already define that option, but could be generally useful. What do you think?

My $0.02: call the option docs (or doc). That's very simple, and agnostic to the actual documentation tool in use. I wouldn't call it gtkdoc because this tool has become disfavored and its use is likely to decline over the next few years.

I'm a member of a the release team, but this is just my personal opinion: I don't like this option sharing business (I guess I'm just not a fan of submodules in general).

My $0.02: I think having a few standard options is useful to promote consistency, if used judiciously only where it makes sense to do so. A docs option makes sense to me.

[eli-schwartz]

Refactored the preliminary cleanups into #9735

[tristan957]

I feel like this isn't going to be good. Say I am contributing to GTK 3 and using a GLib subproject. I probably don't want to build the gtk-docs for GLib as well. I just want to build the docs for GTK3. Would be a huge waste of time to build the GLib docs as well. Unless I can set subproject:gnome.doc?

[xclaesse]

Maybe add a per-subproject builtin option doc, then try dealing with project that define similar option already?