README

   1
   2 GTK+ DocBook Documentation Generator
   3 ====================================
   4
   5 GTK-Doc is used to document C code. It is typically used to document the public
   6 API of libraries, such as the GTK+ and GNOME libraries, but it can also be
   7 used to document application code.
   8
   9 Note that GTK-Doc wasn't originally intended to be a general-purpose
  10 documentation tool, so it can be a bit awkward to setup and use.
  11 For a more polished general-purpose documentation tool you may want to look
  12 at Doxygen (http://www.doxygen.org/). However GTK-Doc has some special code
  13 to document the signals and properties of GTK+ widgets and GObject classes
  14 which other tools may not have.
  15
  16 From your source code comments GTK-Doc generates a Docbook XML document, which
  17 is then transformed into HTML and/or PDF.
  18 The generated HTML documentation can be browsed in an ordinary web browser or
  19 by using the special Devhelp API browser
  20 (see http://developer.imendio.com/wiki/Devhelp).
  21
  22 Please use DoxBook XML instead of DocBook SGML - support for the later will be
  23 dropped.
  24
  25 Requirements
  26 ============
  27
  28 Python 2.7, 3.x - the secondary scripts are written in Python
  29     http:///www.python.org
  30
  31 Python-six - for python 2,3 compatibility
  32
  33 For XML output (recommended):
  34
  35 The DocBook XML DTD.
  36     http://www.oasis-open.org/docbook/
  37
  38 The DocBook XSL Stylesheets.
  39     http://docbook.sourceforge.net/projects/xsl/
  40
  41 libxslt & libxml2 >= 2.3.6.
  42     http://xmlsoft.org/
  43
  44 Most distributions now have packages for all of these, so I would strongly
  45 advise that you grab those.
  46
  47 See the documentation in the help/manual directory for more information. You can
  48 read it e.g. with yelp file://$PWD/help/manual/C/gtk-doc-manual.xml
  49
  50
  51 Building
  52 ========
  53
  54 We are supporting two build systems to build gtk-doc for some transitions time.
  55
  56
  57 Build using auto*
  58 -----------------
  59
  60 In order to build with a the classic auto* system use these commands:
  61
  62 Build from git:
  63 ./autogen.sh; make
  64
  65 Build from dist tarball:
  66 ./configure; make
  67
  68 There are a few parameters one can pass to ./configure, run ./configure --help
  69 to see them. Also ./autogen.sh can take those settings (and will hand them
  70 through to ./configure).
  71
  72 To run the tests:
  73 make check
  74
  75 To install:
  76 make install
  77
  78 To make a release:
  79 make distcheck
  80 or
  81 make dist
  82
  83
  84 Build using meson
  85 -----------------
  86
  87 Support for meson is new and still experiemntal.
  88
  89 Build it from git:
  90 meson build .
  91 ninja -C build
  92
  93 There are some options one can specify too:
  94 meson build . --prefix=
  95 meson build . -Dautoconf_support=false
  96 meson build . -Dcmake_support=false
  97 meson build . -Dyelp_manual=false
  98
  99 To run tests:
 100 ninja -C build test
 101
 102 To install:
 103 ninja -C build install
 104
 105 To make a release:
 106 ninja -C build dist