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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
.. SPDX-FileCopyrightText: 2021 GNOME Foundation
..
.. SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
===============
Using GI-DocGen
===============
In order to use GI-DocGen, you will need:
- a library using GObject and generating introspection data as part of its
build process
- a project configuration file
For the former, you should read `the gobject-introspection documentation <https://gi.readthedocs.io/en/latest/>`__,
which includes all the details on how to write introspectable API.
Writing a project configuration file
------------------------------------
The project configuration file provides some basic information describing your
project, expressed in key/value pairs, and will be exposed to the template
system used when generating the API reference through gi-docgen. Not every key
is mandatory, and the template will decide whether or not use its value when
generating the API reference. For simplicity, we're going to assume you're using
the "basic" template that is part of gi-docgen.
The project configuration file is written using `ToML <https://toml.io/en/>`__,
and you can use the ``--config`` command line option for gi-docgen.
We begin with the ``library`` preamble:
.. code-block:: toml
# SPDX-FileCopyrightText: 2023 Your Name Here
# SPDX-License-Identifier: CC0-1.0
[library]
description = "The GTK toolkit"
authors = "GTK Development Team"
license = "GPL-2.1-or-later"
browse_url = "https://gitlab.gnome.org/GNOME/gtk/"
repository_url = "https://gitlab.gnome.org/GNOME/gtk.git"
website_url = "https://www.gtk.org"
The keys above will be used in the main landing page for the library.
The copyright and license for the documentation configuration should be
specified using `SPDX syntax <https://reuse.software/tutorial/>`__.
If your project has dependencies, and you wish to display them or cross-link
types and symbols from your API reference, you will need to describe them using
the ``dependencies`` key, for instance:
.. code-block:: toml
# List the dependencies using their GIR namespace
dependencies = [
"GObject-2.0",
"Graphene-1.0",
"Pango-1.0",
"Gdk-4.0",
"Gsk-4.0",
]
Each dependency will need its own object, for instance:
.. code-block:: toml
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://developer.gnome.org/gobject/stable"
The ``name``, ``description``, and ``docs_url`` keys will be used when generating the
list of dependencies on the main landing page.
If you wish to add links to the source code repository for type and symbol
declarations, as well as the location of the documentation source, you will need
a ``source-location`` section:
.. code-block:: toml
[source-location]
# The base URL for the web UI
base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/master/"
# The format for links, using "filename" and "line" for the format
file_format = "{filename}#L{line}"
If your library has additional content, in the form of Markdown files that you
wish to include in the generated API reference, you can use the ``extra`` section:
.. code-block:: toml
[extra]
# A list of Markdown files; they will be parsed using the
# same rules as the documentation coming from the introspection
# data. The path of each file is relative to the content
# directory specified on the command line.
#
# The order in which they are included will be used when
# generating the index.
#
# The generated files will be placed in the root output directory
content_files = [
"getting_started.md",
"building.md",
"compiling.md",
"running.md",
"question_index.md",
# ...
]
# Additional images referenced by the documentation; their path
# is relative to the content directory specified on the command
# line.
#
# The image files will be copied into the root documentation,
# without replicating the directory structure in which they
# are listed.
content_images = [
"images/aboutdialog.png",
"images/action-bar.png",
"images/appchooserbutton.png",
"images/appchooserdialog.png",
# ...
]
Each additional Markdown file should have its copyright and license specified
as metadata in its header:
.. code-block:: markdown
Title: An Extra Markdown File
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2023 Your Name Here
# An Extra Markdown File
Content starts here…
For more information about the project configuration, please see the
:doc:`project-configuration` page.
Generating the API reference
----------------------------
Once you have a project configuration file, and the introspection data for the
library you wish to document, all you need is to launch the ``gi-docgen`` command
line tool.
You will need to provide:
- the location of the project configuration file
- the location of the additional content files
- additional search paths for the dependencies
- the output directory for the generated files
- the location of the introspection file
A simple invocation for the installed ``Gtk-4.0.gir`` file is:
.. code-block:: shell
gi-docgen generate -C gtk4.toml /usr/share/gir-1.0/Gtk-4.0.gir
This will generate the API reference for the ``Gtk-4.0`` namespace, and will put
the generate files under the current directory.
|
