Where/how is the docs.gtk.org/gtk3/ API reference generated?

Infrastructure
,
1

From a practical, infrastructure sense, I’m trying to figure out where the generation of the documentation at https://docs.gtk.org/gtk3/ actually happens.

I’ve worked out that it isn’t part of the build process for the Teams / Websites / www.gtk.org · GitLab project itself. And while I see where https://docs.gtk.org/gtk4/ and friends are generated during Gtk4 CI runs, the only similar rules in the CI for the gtk-3-24 branch are gtk-doc (not gi-docgen) based, and not published from the CI.

Oh, wait, never mind. I think I just found it. Well, I’ll leave this here for anyone else who might be wondering the same thing someday:

It appears that, while most of the documentation generation has been moved to the CI for the projects in question, there’s still a docs-gtk-org branch of https://gitlab.gnome.org/GNOME/gtk/ that’s used to publish a few legacy API docs. Possibly just gtk3, gdk3, atk, and atspi2.

Why do I care?

I’m asking because I’m trying to figure out why there would be a difference in how the Gtk3 Gtk.accelerator_parse and Gtk4 Gtk.accelerator_parse pages render angle-bracketed strings like <Control><Shift>F1.

The Gtk3 doc comment source on the gtk-3-24 branch is:

/**
 * gtk_accelerator_parse:
 * @accelerator: string representing an accelerator
 * @accelerator_key: (out) (allow-none): return location for accelerator
 *     keyval, or %NULL
 * @accelerator_mods: (out) (allow-none): return location for accelerator
 *     modifier mask, %NULL
 *
 * Parses a string representing an accelerator. The format looks like
 * `<Control>a` or `<Shift><Alt>F1` or `<Release>z` (the last one is
 * for key release).
 *
 * The parser is fairly liberal and allows lower or upper case, and also
 * abbreviations such as `<Ctl>` and `<Ctrl>`. Key names are parsed using
 * gdk_keyval_from_name(). For character keys the name is not the symbol,
 * but the lowercase name, e.g. one would use `<Ctrl>minus` instead of
 * `<Ctrl>-`.

The Gtk4 doc comment on the main branch is:

/**
 * gtk_accelerator_parse:
 * @accelerator: string representing an accelerator
 * @accelerator_key: (out) (optional): return location for accelerator keyval
 * @accelerator_mods: (out) (optional): return location for accelerator
 *   modifier mask
 *
 * Parses a string representing an accelerator.
 *
 * The format looks like “`<Control>a`” or “`<Shift><Alt>F1`”.
 *
 * The parser is fairly liberal and allows lower or upper case, and also
 * abbreviations such as “`<Ctl>`” and “`<Ctrl>`”.
 *
 * Key names are parsed using [func@Gdk.keyval_from_name]. For character keys
 * the name is not the symbol, but the lowercase name, e.g. one would use
 * “`<Ctrl>minus`” instead of “`<Ctrl>-`”.
 *

But the docs-gtk-org-branch’s Gtk-3.0.gir file (used to generate the Gtk3 docs) contains this (which doesn’t seem to match the gtk-3-24 branch source):

      <doc xml:space="preserve"
           filename="gtk/gtkaccelgroup.c"
           line="1434">Parses a string representing an accelerator. The format looks like
“&lt;Control&gt;a” or “&lt;Shift&gt;&lt;Alt&gt;F1” or “&lt;Release&gt;z” (the last one is
for key release).

The parser is fairly liberal and allows lower or upper case, and also
abbreviations such as “&lt;Ctl&gt;” and “&lt;Ctrl&gt;”. Key names are parsed using
gdk_keyval_from_name(). For character keys the name is not the symbol,
but the lowercase name, e.g. one would use “&lt;Ctrl&gt;minus” instead of
“&lt;Ctrl&gt;-”.
<!-- ... -->
        </doc>

While the Gtk-4.0.gir file installed on my Fedora 43 system, presumably matching the one used by the Gtk4 CI to generate its docs, contains:

      <doc xml:space="preserve"
           filename="gtk/gtkaccelgroup.c"
           line="485">Parses a string representing an accelerator.

The format looks like “`&lt;Control&gt;a`” or “`&lt;Shift&gt;&lt;Alt&gt;F1`”.
      
The parser is fairly liberal and allows lower or upper case, and also
abbreviations such as “`&lt;Ctl&gt;`” and “`&lt;Ctrl&gt;`”.

Key names are parsed using [func@Gdk.keyval_from_name]. For character keys
the name is not the symbol, but the lowercase name, e.g. one would use
“`&lt;Ctrl&gt;minus`” instead of “`&lt;Ctrl&gt;-`”.
<!-- ... -->
     </doc>

Thus, the Gtk4 docs render correctly, while the Gtk3 docs end up with (what appear to be) spurious HTML tags that get swallowed by the browser’s HTML render engine.

So I guess my question now morphs into, “How/where is the docs-gtk-org branch Gtk-3.0.gir file generated, and from what source?”

2

Any fix to the GTK3 documentation needs manual intervention.

The introspection data included in the docs-gtk-org branch is whatever I commit whenever I remember to update the docs.

The GTK3 documentation still uses gtk-doc, but it was not completely ported over to the Markdown subset that gtk-doc started supporting a while ago; this means that there are some places where the GTK3 documentation still embeds XML entities that would be automatically escaped. On top of that, the structure and contents of the documentation are still very much not meant for gi-docgen, but since gtk-doc is unmaintained, and it cannot be used to render a website like docs.gtk.org, the path of least resistance is to just wing it.

1 Like
3

Gotcha, that makes sense.

Hmm. What would you recommend for submitting fixes, then? I could submit MRs against the docs-gtk-org branch to edit the Gtk-3.0.gir file on that branch directly? Then new HTML can be generated from that?

Might be the path of least resistance, since it sounds like generating that file from the gnome-3-24 branch sources is… an indirect, and possibly quite involved, process? (And the changes would mostly be minor & cosmetic, like wrapping &lt;control&gt;&lt;shift&gt;a in backticks so that gi-docgen preserves the entity-escaped angle brackets.)

4

You can still fix the documentation in the gtk-3-24 branch, especially when it comes to XML elements and entities still left over from the Markdown port. You can also fix some of the formatting, like lines that start with a # and are interpreted as a heading, or indentations above four spaces that are considered a preformatted block; gtk-doc will not care, but the output on gi-docgen will improve. The only things that won’t work are:

  • using gi-docgen cross-links instead of gtk-doc references
  • dropping SECTION blocks

as those would require porting the GTK3 API reference generation to gi-docgen entirely.

I routinely update the GTK3 introspection data on the docs-gtk-org branch, though I could also see if I can modify the CI pipeline to pull introspection data from the CI artefacts.