Move from gtk-doc to gi-docgen for reference api

[jsparber]

Since appstream is introspectable it can use gi-docgen to generate the reference api documentation. This would ensure that the language bindings also include all documentation strings, which currently isn't the case.

For more reasons see: https://gitlab.gnome.org/GNOME/gtk/-/merge_requests/3222

[hughsie]

fwupd moved from gtk-doc to docgen (with a few months of supporting both!) and so far it's a much better experience. If that helps!

[ximion]

I find it a bit harder to use the new HTML generated by gi-docgen (links to the old documentation fail to work with the new pages, a lot of old GLib documentation seems to have just vanished, the overview pages for classes are less detailed to more clicks are required to get all information, etc. - the search feature is great though!), but there is no doubt in my mind that this tool is the future and that AppStream should make this switch sooner rather than later - gtk-docgen is really showing its age and has its own class of issues (and is more and more a pain to work with, and also slow), so yeah, +1 :-)

My only real concerns are backwards compatibility (probably a non-issue since AppStream's GLib requirements and especially Meson requirements are high-ish already for the latest versions, and distributions satisfying those will likely have gi-docgen available or backported) and that I need to find out if functions marked as (skip) are still included in the docs (I think the answer to that is "yes" though), because otherwise the C documentation would suffer, as I need to use "skip" this a lot more to generate better language bindings in the future (mostly thanks to https://gitlab.gnome.org/GNOME/gobject-introspection/-/issues/305).

[bilelmoussaoui]

lot of old GLib documentation seems to have just vanished

GLib is a bad example here because it doesn't use gi-docgen upstream, it is a deployed version in gtk's docs for now and so a lot of the documentation have not been ported properly.

[ximion]

Ah, that explains a lot! I still search for cached GLib docs and docs in other places for info that I miss in the docs on gtk.org.
It's not a problem at all for AppStream though, libappstream(-compose) are way simpler libraries and don't have overly complex documentation :-)