It’s been nearly a month since I’ve talked about gi-docgen, my little tool to generate API references from introspection data. In between my blog post and now, a few things have changed:
- the generated API reference has had a few improvements, most notably the use of summaries in all index pages
- all inheritable types now show the properties, signals, and methods inherited from their ancestors and from the implemented interfaces; this should hopefully make the reference much more useful for newcomers to GTK
- we allow cross-linking between dependent namespaces; this is done using an
optional URL map, with links re-written on page load. Websites hosting
the API reference would need only to provide an
urlmap.jsfile to rewrite those links, instead of doing things like parsing the HTML and changing thehrefattribute of every link cough library-web cough - we parse custom GIR attributes to provide better cross-linking between methods, properties, and signals.
- we generate an index file with all the possible end-points, and a dictionary of terms that can be used for searching; the terms are stemmed using the Porter stemming algorithm
- the default template will let you search using the generated index; the
search supports scoping, so using
method:show widgetwill look for all the symbols in which the termshowappears in method descriptions, alongside thewidgetterm - we also generate a DevHelp file, so theoretically DevHelp can load up the API references built by gi-docgen; there is still work to be done, there, but thanks to the help of Jan Tojnar, it’s not entirely hopeless
Thanks to all these changes, both Pango and GTK have switched from gtk-doc to gi-docgen for their API references in their respective main development branches.
Now, here’s the part where it gets complicated.
Using gi-docgen
Quick reminder: the first and foremost use case for gi-docgen is GTK (and some of its dependencies). If it works for you, I’m happy, but I will not go out of my way to make your use case work—especially if it comes at the expense of Job #1, i.e. generating the API reference for GTK.
Since gi-docgen is currently a slightly moving target, I strongly recommend using it as a Meson subproject. I also strongly recommend vendoring it inside your release tarballs, using:
meson dist --include-subprojects
when generating the distribution archive. Do not try and depend on an installed copy of gi-docgen.
Additionally, it’s possible to include the gi-docgen API reference into the Meson tarball by using a dist script. The API reference will be re-generated when building, but it can be extracted from the tarball, like in the good old gtk-doc-on-Autotools days.
Publishing your API reference
The tool we use to generate developer.gnome.org, library-web, is unmaintained and, quite frankly, fairly broken. It is a Python2 script that got increasingly more complicated without actually getting more reliable; it got progressively more broken once we started having more than two GTK modules, and then it got severely broken once we started using Meson and CMake, instead of Autotools. These days, you’ll be lucky to get your API reference uploaded to developer.gnome.org (as a separate archive), and you can definitely forget about cross-linking, because the tool will most likely get things wrong in its quest to restyle any HTML it finds, and then fix the references to what it thinks is the correct place:
The support for Doxygen (which is used by the C++ bindings) is minimal, and it ended up breaking a few times. Switching away from gtk-doc to gi-docgen is basically the death knell for the whole thing:
- first of all, it cannot match the documentation module with the configuration for it, because git-docgen does not have the concept of a “documentation module”; at most, it has a project configuration file.
- additionally, we really don’t want library-web messing about with the generated HTML, especially if the end result breaks stuff.
So, the current solution is to try and make library-web detect if we’re
using gi-docgen, by looking for toml and toml.in files in the release
archive, and then upload various files as they are. It’s a bad and fragile
stop gap solution, but it’s the best we can do without breaking everything
in even more terrible ways.
For GNOME 41 my plan is to sidestep the whole thing, and send library-web to a farm upstate. We’re going to use gnome-build-meta to build the API references of the projects we have in our SDK, and then publish them according to the SDK version.
My recommendation for library authors, in any case, is to build the API reference for the development branch of their project as part of their CI, and then publish it to the GitLab pages space. For instance:
This way, you’ll always have access to the latest documentation.
Sadly, we can’t have per-branch references, because GitLab pages are nuked every time a branch gets built; for that, we’d have to upload the artifacts somewhere else, like an S3 bucket.
Things are going to get better in the near future, after 10 years of stagnation; sadly, this means we’re living in Interesting Times, so I ask of you to please be patient while we transition towards a new and improved way to document our platform.