1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
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
96
97
|
Contents:
0. Using devhelp
1. Building documentation
2. Custom scripts
3. Makefile rules
4. Cruft
===[ 0. Using devhelp ]======================================================
If you install Gwyddion to a system directory, its API documentation should
appear in the table of contents automatically. To find documentation in a
nonstandard location, let's assume $HOME/opt/gwyddion, do either:
export DEVHELP_SEARCH_PATH=$HOME/opt/gwyddion/share/gtk-doc/html
or
mkdir -p ~/.devhelp/books
cd ~/.devhelp/books
for x in $HOME/opt/gwyddion/share/gtk-doc/html/*; do ln -s $x .; done
To integrate devehelp to vim, define
function! DevHelpCurrentWord()
let word = expand("<cword>")
exe "!devhelp -s " . word
endfunction
and map
:call DevHelpCurrentWord<cr>
to a keystroke of your choice.
===[ 1. Building documentation ]=============================================
Building docs takes too much time, they are not built automatically whenever
source code changes. If gtk-doc is found the documentation rebuild rules are
only enabled, not executed. Change to the appropriate dir and run
make docs
if you want to update the API documentation.
===[ 2. Custom scripts ]=====================================================
Almost everything is generated, pay attention as other gtk-doc employing
projects often let humans maintain much more files. The ONLY human-edited
files are:
- libgwy*-docs.sgml (driver files)
- libgwy*.overrides (symbol overrides)
- content files (optional)
- Makefile templates
The rest is generated:
- libgwy*.types (supported by gtk-doc since 1.8)
- libgwy*-sections.txt (supported by gtk-doc since 1.8)
rationale: if header files are organized reasonably they naturaly form
sections, therefore sections created by gtkdoc-scan are directly
used
tools: add-objects.py adds GwyFoo and GwyFooClass to appropriate sections
for classed types (using libgwy*.hierarchy as class list)
- template/*
rationale: the usual approach when these files are partially generated and
partially human-edited is a source of neverending revision
management pain, therefore *all* section documentation is in the
source code
this directory is usually called tmpl, but it confused CVS if it was kept
after removal
===[ 3. Makefile rules ]=====================================================
gtk-doc.mk are universal rules to be included in every documentation
Makefile.am.
===[ 4. Cruft ]==============================================================
gtk-doc scan may place a slightly broken doctype declaration to
MODULE-docs.sgml
<!doctype book PUBLIC "-//DavenPort//DTD DocBook V3.0//EN" [
fix it to
<!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
or else you'll get really weird errors.
|
