README 2.58 KB
Newer Older
Owen Taylor's avatar
Owen Taylor committed
1 2 3 4

GTK+ DocBook Documentation Generator
====================================

5
GTK-Doc is used to document C code. It is typically used to document the public
Damon Chaplin's avatar
Damon Chaplin committed
6
API of libraries, such as the GTK+ and GNOME libraries, but it can also be
7 8
used to document application code.

Damon Chaplin's avatar
Damon Chaplin committed
9 10 11 12
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 polished general-purpose documentation tool you may want to look
at Doxygen (http://www.doxygen.org/). However GTK-Doc has some special code
13 14
to document the signals and properties of GTK+ widgets and GObject classes
which other tools may not have.
15

16 17
From your source code comments GTK-Doc generates a Docbook XML document, which
is then transformed into HTML and/or PDF.
18 19
The generated HTML documentation can be browsed in an ordinary web browser or
by using the special Devhelp API browser
20
(see https://wiki.gnome.org/Apps/Devhelp).
Owen Taylor's avatar
Owen Taylor committed
21 22 23 24 25


Requirements
============

Stefan Sauer's avatar
Stefan Sauer committed
26
Python 3.x
27
    http:///www.python.org
Damon Chaplin's avatar
Damon Chaplin committed
28

Stefan Sauer's avatar
Stefan Sauer committed
29
Additional python modules:
30
    For the tests: unittest, parameterized
Stefan Sauer's avatar
Stefan Sauer committed
31
    For mkhtml2 (experimental): anytree, lxml and pygments
32
    For fixxref: pygments
33

Damon Chaplin's avatar
Damon Chaplin committed
34 35 36
For XML output (recommended):

The DocBook XML DTD.
37
    http://www.oasis-open.org/docbook/
Owen Taylor's avatar
Owen Taylor committed
38

Damon Chaplin's avatar
Damon Chaplin committed
39 40
The DocBook XSL Stylesheets.
    http://docbook.sourceforge.net/projects/xsl/
Owen Taylor's avatar
Owen Taylor committed
41

Stefan Kost's avatar
Stefan Kost committed
42
libxslt & libxml2 >= 2.3.6.
43 44
    http://xmlsoft.org/

45 46
Most distributions now have packages for all of these, so I would strongly
advise that you grab those.
Owen Taylor's avatar
Owen Taylor committed
47

48 49
See the documentation in the help/manual directory for more information. You can
read it e.g. with yelp file://$PWD/help/manual/C/gtk-doc-manual.xml
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95


Building
========

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


Build using auto*
-----------------

In order to build with a the classic auto* 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 and still experiemntal.

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

There are some options one can specify too:
meson build . --prefix=
96
meson build . -Dautotools_support=false
97 98 99 100 101 102 103 104 105 106 107
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