Documenting with gtk-doc

gtk-doc has been selected as the recommended tool to generate documentation for software API in Apertis.

Why gtk-doc

3 tools were good candidates:

  • gtk-doc
  • gi-docgen
  • doxygen

The main reasons behind choosing gtk-doc are:

  • Supports GObject introspection
  • Supports documentation generated by gdbus-codegen
  • Supports devhelp
  • Can be used for any C library

Doxygen lacks GObject introspection and devhelp support but can parse multiple languages.

gi-docgen is to be used only with GObject Introspection code and the project recommends to only use it for that.

As Apertis APIs are mainly written in C with Gtk, gtk-doc was deemed the best option.

Setting up

The setup with autotools is described in gtk-doc’s sources It can also easily be setup with meson.

Note that the debian packaging that generates the build files (dh-autoreconf) doesn’t run gtkdocize (See this commit).

It is recommended to run it manually in the debian/rules file (after creating the needed m4 directory):

override_dh_autoreconf:
        mkdir -p m4
        gtkdocize --copy
        dh_autoreconf

Installing documentation

The documentation should be installed in /usr/share/gtk-doc/html/<project_name>.

More recent versions of devhelp support looking up documentation in /usr/share/doc but we recommend not using it as different versions of devhelp are used in different versions of Apertis.

Running checks

It is recommended to run the gtk-doc checks on what has been generated. See the end of the example Makefile If left uncommented, the debian packaging will run the checks.

Those checks are usefull to avoid forgetting to document new code or updating documentation when the API changes.

It will show errors like this:

Running suite(s): gtk-doc-libcroesor
libcroesor-undocumented.txt:1:E: 38 undocumented or incomplete symbols

The different files contain:

  • MODULE-undocumented.txt: Symbols that have no documentation,
  • MODULE-unused.txt: Symbols that are documented but not present in the generated documentation,
  • MODULE-undeclared.txt: Symbols present in the generated documentation but not existing in the code.

Porting documentation

Porting from hotdoc is quite straightforward. The main things to change is the files description: each source file (or header) must have a long and short description for the file. This can consist of a simple See #Type.

With checks activated, some other errors can be reported for some missing or out-of-date documentation blocks. They need to be updated.

Ignoring autogenerated files

Some autogenerated files can be missing documentation but they can be ignored by gtk-doc by adding --ignore-headers <files> to the SCAN_OPTIONS variable in the documentation Makefile.

The file section should also be removed from the MODULE-sections.txt file or the check will complain about undeclared symbols.

Adding DBus documentation

The dbus Object Introspection XML files are not parsed by gtk-doc. Their documentation can be generated separately with gdbus-codegen:

gdbus-codegen \
    --interface-prefix org.apertis. \
    --c-namespace Rsdpriv \
    --generate-docbook librhosydd/docs/dbus \
    $(srcdir)/librhosydd/org.apertis.Rhosydd1.Vehicle.xml

This will generate a DocBook file in librhosydd/docs/dbus that can be included to the main gtk-doc DocBook file (In the case of rhosydd, we add <xi:include href="dbus-org.apertis.Rhosydd1.Vehicle.xml"/> in librhosydd/docs/librhosydd-docs.sgml).

The gdbus-codegen command can be run manually when the documenation needs updating but it is recommended to run it in the Makefile, the same way gdbus-codegen is used to generate source files to be safer. See how it is done in rhosydd. (This link may need updating)

Adding markdown documentation

gtk-doc doesn’t support Markdown, it only supports DocBook. Because Markdown in more reader friendly that DocBook, it is recommended to write out-of-source documentation in Markdown and manually generate a DocBook file from it when it changes. Both Markdown and DocBook files should be added on the git repository.

To generate a DocBook file from Markdown, pandoc can be used:

pandoc --wrap=none -t docbook overview.markdown -o overview.xml

Unfortunately, this format is not understoodd as is by gtk-doc. The XML section node must be cleaned out:

<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="libcroesor-overview">

is replaced by

<section xml:id="libcroesor-overview">

The links must also be adapted to what gtk-doc can understand:

<link xlink:href="www.apertis.org">Apertis</link>

is replaced by

<ulink role="online-location" url="www.apertis.org">Apertis</ulink>

Then, the generated DocBook can be added to the main DocBook file:

<xi:include href="overview.xml"/>

Adapting template

The autogenerated main DocBook file may not be complete. For example, the [Insert title here] should be replaced with a nice title for the section.

Fixing role attribute

In some versions of gtk-doc (at least 1.33.1), the template is generated with the role attribute in the index tag.

This role attribute confuses gtkdoc-mkhtml and makes it skip the generation of HTML files for the linked DocBook files, but still generates a link to those missing files.

To fix the issue, all the role attributes should be removed in the template .sgml file.