Hi all;
this is going to be a long email, so please bear with me.
tl;dr: the current state of
developer.gnome.org can be described, by and large, with "a huge mess"; we need to phase out the existing stack, and I have a good idea of how to make that happen.
On the technical side: library-web is a Python 2 application that is basically tied to the way things have been done in the past. It requires projects to ship a full render of their gtk-doc-based API reference in their release archives—something that will be discarded by distributions and users alike, and it's only needed for library-web; it also parses the generated HTML to inject a different CSS (as if we didn't control gtk-doc ourselves), and changes the cross-reference links to remove the absolute paths to the maintainer's file system with URLs to
developer.gnome.org. Sadly, library-web is currently unmaintained; this means it cannot deal with changes in our build systems (from Autotools to CMake or Meson, which do not distribute the API reference in the release archive), or changes in the tools we use to generate the API reference itself (from gtk-doc to gi-docgen). I'll skip the fact that gtk-doc is also unmaintained, which means stuff is breaking apart on multiple fronts.
From the perspective of a developer of a bunch of libraries in the core GNOME stack the situation has slowly drifted from being broken to become entirely untenable. Early this year I wrote an entirely new tool to replace gtk-doc in order to generate the API reference of GTK4; while I'm being clear that the goal of the tool is to document GTK and a couple of its dependencies (like Pango and GdkPixbuf), I'm also aware that other projects are looking at it to replace gtk-doc.
Of course, replacing gtk-doc means that library-web is currently unable to even deal with it; I tried to modify library-web[1] to get it to publish the documentation and leaving it alone, but it turns out that it's harder than it looks, and it's even harder to gather logs out of our infrastructure. I also tried to run a container with library-web on my machine, to understand what it is doing, but in practice it's just a black box. This led to the GTK project publishing the API reference on its own
gtk.org domain[2], though the CI pipeline, at least for the time being.
From the technical side, this Jenga pile. held together by hopes and dreams, has to go away.
We build all our libraries to publish the GNOME run times anyway; ideally, we should be publishing the `org.gnome.Sdk.Docs` run time, but that kind of broke with the switch to Buildstream. I'm currently looking at ways to fix that, and then publishing the API references of all our stack as part of our build process, just like we publish releases and VM for GNOME OS. The idea is to have a versioned area so you can ask for the API references for GNOME 40, 41, etc. in the form of:
- all bleeding edge builds from the main development branch
- ...
This way you only ask for the documentation related to the version of the GNOME SDK you want.
On the content side: there's a huge chunk of articles, guides, and tutorials that are either written for GNOME 2 or early GNOME 3; they are hard to update, hard to search for, and hard to contribute to.
The Design team is moving the HIG[3] to a Sphinx set up, which publishes the rendered documentation through a CI pipeline on GitLab pages. I used the same theme and set up to render the current
developer.gnome.org in my personal space:
I'm in the process of:
- vetting the current content of
developer.gnome.org, dropping the GNOME2 and early GNOME3 stuff
- editing the programmers guide to drop outdated content
- re-organising the accessibility and localisation guidelines into their own sections, possibly moving some of the content into the HIG
- re-organising the HowDoI wiki pages into proper tutorials, with the goal of dropping them from the wiki
The audience is geared towards GNOME 40 and GTK4 as a baseline.
Ideally, I'd like to tweak the Sphinx output to point each page to its location on the Git repository, so that it's possible to quickly edit the content through the GitLab web UI. My experience with doing that on the
gtk.org website has been a net positive, with a good deal of engagement from new contributors.
The end goal is to phase out the API references section of
developer.gnome.org, moving that to a new, auto-generated website built by our CI/CD pipeline; the remaining content of
developer.gnome.org will be vetted, and refreshed, in order to be published on its own CI pipeline.
There is one last thing that library-web does, and it's: publishing the GNOME release notes, the application help, and the administrators guide. I think Shaun has some ideas on the application help, and we can probably figure out a similar arrangement for the release notes (which have been painful to deal with for a while, now) and the administrators guide.
I'm happy to talk specifics on the plan's outline, if people have questions.
Ciao,
Emmanuele.
