GTK-Doc - Documentation generator for C code
============================================

Development and maintenance status (December 2023)
--------------------------------------------------

The GTK-Doc project is looking for additional co-maintainers, volunteers for
reviewing merge requests and releasing new versions.

The project is currently under-maintained, doesn't receive funding support and
thus relies on voluntary work.

That being said, GTK-Doc is still there and can still be used successfully. Some
people still like (and prefer) the GTK-Doc output, combined with the Devhelp API
browser.

Comments welcome at: https://gitlab.gnome.org/GNOME/gtk-doc/-/issues/151

Important message
-----------------

To generate the `api-index-*.html` files, you need to use docbook-style-xsl
version 1.79.1, not the latest version.

See:
- https://sourceforge.net/p/docbook/bugs/1401/
- https://gitlab.gnome.org/GNOME/gtk-doc/-/issues/36

Introduction
------------

GTK-Doc is used to document C code. It is typically used to document the public
API of libraries, such as GLib-based libraries, but it can also be used to
document application code.

Note that GTK-Doc wasn't originally intended to be a general-purpose
documentation tool, so it can be a bit awkward to setup and use.
For a more general-purpose documentation tool you may want to look at
Doxygen (http://www.doxygen.org/). However GTK-Doc has some special code to
document the signals and properties of GTK widgets and GObject classes which
other tools may not have.

From your source code comments GTK-Doc generates a DocBook XML document, which
is then transformed into HTML and/or PDF.
The generated HTML documentation can be browsed in an ordinary web browser or
by using the special Devhelp API browser
(see https://wiki.gnome.org/Apps/Devhelp).

Requirements
------------

Python 3.x
    http:///www.python.org

Additional python modules:
    For the tests: unittest, parameterized
    For mkhtml2 (experimental): anytree, lxml and pygments
    For fixxref: pygments

For XML output (recommended):

The DocBook XML DTD.
    http://www.oasis-open.org/docbook/

The DocBook XSL Stylesheets.
    http://docbook.sourceforge.net/projects/xsl/

libxslt & libxml2 >= 2.3.6.
    http://xmlsoft.org/

For PDF output:

the dblatex tool.
    http://dblatex.sourceforge.net/

Most distributions now have packages for all of these, so I would strongly
advise that you grab those.

See the documentation in the help/manual/ directory for more information. You
can read it for example with yelp: `yelp help/manual/C/index.docbook`.

Building
--------

We are supporting two build systems to build gtk-doc for some transitions time.

### Build using the Autotools

In order to build with the classic Autotools system use these commands:

Build from git:
./autogen.sh; make

Build from dist tarball:
./configure; make

There are a few parameters one can pass to ./configure, run ./configure --help
to see them. Also ./autogen.sh can take those settings (and will hand them
through to ./configure).

To run the tests:
make check

To install:
make install

To make a release:
make distcheck
or
make dist

### Build using Meson

Support for Meson is new.

Build it from git:
meson build .
ninja -C build

There are some options one can specify too:
meson build . --prefix=
meson build . -Dautotools_support=false
meson build . -Dcmake_support=false
meson build . -Dyelp_manual=false

To run tests:
ninja -C build test

To install:
ninja -C build install

To make a release:
ninja -C build dist