GObject Introspection Doctools

Abstract

Doctools allows you to build library documentation directly from .gir files. The output is adjusted according to which programming language you're generating docs for (only C and Python are currently supported). The GObject Introspection Doctools project aims to replace gtk-doc as the main documentation generator for GNOME.

Status

Doctools is a work in progress and can be considered Alpha software.

Building the tools

As of now you will need various modules from git master to experiment with the doctools. When Gnome 3.4 is released these tools should be packaged in any distro which ships the latest Gnome releases. The easiest way to build the doctools is using JHBuild.

$> jhbuild build yelp yelp-tools gobject-introspection

Workflow

g-ir-doc-tool -> mallard -> yelp-build -> html/yelp/etc.

Example of generating C documentation in HTML from a .gir file

$> g-ir-doc-tool --language C -o ./output_dir /usr/share/gir-1.0/Gtk-3.0.gir
$> yelp-build html .
$> $BROWSER index.html

Example of generating Python documentation in Mallard from a .gir file

Yelp supports opening Mallard files (and the rendering's a little nicer than the HTML output), so you can bypass the HTML/browser:

$> g-ir-doc-tool --language Python -o ./output_dir /usr/share/gir-1.0/Gtk-3.0.gir
$> yelp ./output_dir/index.page

Example of generating JavaScript (GJS) documentation in HTML from a .gir file

$> jhbuild run g-ir-doc-tool --language=gjs -o ./dir_where_you_want_docs path/to/*.gir
$> yelp-build html .

**If your build doesn't work, you may need to install python-mako