Documenting with gtk-doc
gtk-doc has been selected as the recommended tool to generate
documentation for software API in Apertis.
3 tools were good candidates:
The main reasons behind choosing gtk-doc are:
- Supports GObject introspection
- Supports documentation generated by
- Can be used for any C library
Doxygen lacks GObject introspection and
devhelp support but can parse
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
The setup with autotools is described in
It can also easily be setup with meson.
Note that the debian packaging that generates the build files (
gtkdocize (See this commit).
It is recommended to run it manually in the
debian/rules file (after creating
override_dh_autoreconf: mkdir -p m4 gtkdocize --copy dh_autoreconf
The documentation should be installed in
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.
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.
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
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
gtk-doc by adding
--ignore-headers <files> to the
variable in the documentation
The file section should also be removed from the
MODULE-sections.txt file or
the check will complain about undeclared symbols.
Adding DBus documentation
dbus Object Introspection XML files are not parsed by
Their documentation can be generated separately with
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
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
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
The links must also be adapted to what
gtk-doc can understand:
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:
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
role attribute in the
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
To fix the issue, all the
role attributes should be removed in the template