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
|
<!--
SPDX-FileCopyrightText: 2019 Sébastien Wilmet <swilmet@gnome.org>
SPDX-License-Identifier: CC-BY-SA-4.0
-->
<page xmlns="http://projectmallard.org/1.0/"
xmlns:its="http://www.w3.org/2005/11/its"
type="topic"
id="installing-api-documentation">
<info>
<link type="guide" xref="index" />
</info>
<title>Installing API documentation</title>
<synopsis>
<p>How <app>Devhelp</app> finds the API documentation.</p>
</synopsis>
<links type="section" />
<section id="book-format">
<title>Book format</title>
<p>
See <link xref="book-format" /> for information on the API documentation
format that <app>Devhelp</app> recognizes.
</p>
</section>
<section id="books-locations">
<title>Books locations</title>
<p>
Once a book follows the right format, its directory needs to be installed
at a location where <app>Devhelp</app> will find it.
</p>
<p>
<app>Devhelp</app> uses the
<link href="https://specifications.freedesktop.org/basedir-spec/latest/">XDG Base Directory Specification</link>
to find the books. The list of locations searched is:
</p>
<list its:translate="no">
<item><p><code>$XDG_DATA_HOME/devhelp/books/</code></p></item>
<item><p><code>$XDG_DATA_HOME/gtk-doc/html/</code></p></item>
<item><p><code>$XDG_DATA_DIRS/devhelp/books/</code></p></item>
<item><p><code>$XDG_DATA_DIRS/gtk-doc/html/</code></p></item>
</list>
<p>
Note that the two latter consist of lists of directories to look for.
Directory values are separated by <code>:</code> characters. Those
environment variables are normally set up by the desktop environment or
distribution.
</p>
<p>
Examples of locations to index files with <code>$XDG_DATA_HOME</code> on a
typical system:
</p>
<list>
<item its:translate="no"><p>
<file>~/.local/share/devhelp/books/glib/glib.devhelp2</file>
</p></item>
<item><p>
<file>~/.var/app/org.gnome.Devhelp/data/devhelp/books/glib/glib.devhelp2</file>
if <app>Devhelp</app> is launched with
<link href="https://flatpak.org/">Flatpak</link>.
</p></item>
</list>
<p>
Example of a location to an index file with <code>$XDG_DATA_DIRS</code> on
a typical system:
</p>
<list>
<item its:translate="no"><p>
<file>/usr/share/gtk-doc/html/glib/glib.devhelp2</file>
</p></item>
</list>
</section>
<section id="gtk-doc">
<title>GTK-Doc</title>
<p>
<link href="https://gitlab.gnome.org/GNOME/gtk-doc">GTK-Doc</link> is a
tool to generate API documentation from comments added to C code. It is
used by GLib, GTK and GNOME libraries and applications.
</p>
<p>
GTK-Doc installs the API reference of a module into:
</p>
<p its:translate="no">
<code>$datadir/gtk-doc/html/$module_name/</code>
</p>
<p>
It follows the book format supported by <app>Devhelp</app>. So by using
GTK-Doc, the API reference can be browsed in <app>Devhelp</app>
automatically (once installed in the right location, that is).
</p>
</section>
</page>
|
