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? 🙂

2 thoughts on “GTK-Doc, Devhelp and [insert here missing GNOME project]”

Leave a Reply

Your email address will not be published. Required fields are marked *