GTK-Doc, Devhelp and [insert here missing GNOME project]

In GNOME, the API documentation is written with GTK-Doc. For each module, it generates HTML pages plus a *.devhelp2 index file. Then the documentation can be easily browsed and searched in the Devhelp application.

While GTK-Doc alone and Devhelp alone work fine, things get more complicated with cross-references: when there are links to symbols that belong to other modules. GTK-Doc handles this with gtkdoc-fixxref, but it needs to be correctly configured in the build system of each module.

Then things get more complicated when installing pre-built documentation, instead of requiring every developer to build the gtk-doc documentation of every module that he/she cares about. Linux distributions have packages to install such documentation, but the cross-references may be broken.

With BuildStream and gnome-build-meta, I think it would be feasible to:

  • Build all the API documentation of GNOME and host the result on a server.
  • Finally say goodbye to cross-reference link problems.
  • Have a CLI tool to download the latest GNOME API docs and install them in the right place so that Devhelp picks them. Bonus point if you can choose the version, stable vs development, etc.
  • Publish also these docs on developer.gnome.org.

I’ve just described the [insert here missing GNOME project] thing. It can be – and should be – done independently of both GTK-Doc and Devhelp. I cannot offer you mentoring help on this project, I’m already sufficiently busy with gedit and Tepl; but GTK-Doc, Devhelp and BuildStream are normally well documented.

If you’re bored, it’s a project that would be tremendously useful to all developers that use the “G platform”. Any takers? 🙂

Small tip with GTK-Doc, Devhelp, JHBuild and Fedora

And docbook-style-xsl.

docbook-style-xsl bug with GTK-Doc on Fedora

On Fedora, building GTK-Doc API documentation is buggy since several years, normally each module contains the following indexes:

  • For each version, the list of new symbols, for example “Index of new symbols in 3.36”.
  • The “Index of deprecated symbols”.

These indexes are very useful to keep up with new versions of libraries, in addition to reading the NEWS files. On Fedora, these indexes are not generated by default.

It’s because of this bug: gtk-doc one, fedora one, docbook one.

Simple fix on Fedora: downgrade docbook-style-xsl to version 1.79.1 and add this line to your /etc/dnf/dnf.conf:

excludepkgs=docbook-style-xsl

Then rebuild the GTK-Doc API documentation of the modules you care about, for example in JHBuild for GLib add this to your jhbuildrc:

module_mesonargs['glib'] = '-Dgtk_doc=true'

Then run Devhelp in a jhbuild shell, you can add this alias to your bashrc:

alias devhelp='jhbuild run devhelp'

or (additional small tip):

alias devhelp='jhbuild run devhelp --new-window'

Enjoy! Now you can finally keep up with what’s new in GLib, from the comfort of the Devhelp API browser application 🙂

(Sorry for the not-very-interesting blog post, with a bit of hope the bug will be fixed upstream in docbook-style-xsl, or Fedora will follow the recommendation of the upstream developer to package the previous version instead).