1
2
3GI-DOCGEN(1) User Commands GI-DOCGEN(1)
4
5
6
8 gi-docgen - a documentation generator using gobject-introspection
9
11 gi-docgen COMMAND [OPTION...] GIR_FILE
12
14 GI-DocGen is a document generator for GObject-based libraries. GObject
15 is the base type system of the GNOME project. GI-DocGen uses the ma‐
16 chine readable introspection data provided by GObject-based libraries
17 in order to generate the API reference of these libraries, as well as
18 other ancillary documentation.
19
20 The main gi-docgen executable provides various subcommands to access
21 all its functionality.
22
23
25 All commands have the following options:
26
27
28 --quiet
29 do not print details of the current operation
30
31 --fatal-warnings
32 make warnings fatal errors
33
34 --help print command line help
35
36
38 The generate command provides the main functionality of gi-docgen.
39
40 gi-docgen generate [ OPTIONS ] [ GIR_FILE ]
41
42
43 The generate command will parse the given GIR file, as well as its de‐
44 pendencies, and build an API reference for the namespace it finds in
45 the introspection data. Projects can use a configuration file to con‐
46 trol aspects of the output, as well as provide additional content that
47 should be included in the documentation.
48
49
50 options:
51 --config=FILE
52 use the given project configuration file
53
54 --content-dir=PATH
55 specify the directory where the content files listed in the
56 project configuration file can be found
57
58 --templates-dir=PATH
59 specify the directory where the templates used to generate the
60 documentation can be found
61
62 --theme-name=NAME
63 specify the template name to be used when generating the docu‐
64 mentation, overriding the project's configuration
65
66 --output-dir=PATH
67 create the documentation under the given directory
68
69 --no-namespace-dir
70 generate all documentation files directly under the output di‐
71 rectory, instead of creating a directory using the namespace
72 name and version
73
74 --add-include-path=PATH
75 add a directory to the path which the scanner uses to find GIR
76 files. Can be used multiple times to specify multiple directo‐
77 ries
78
79 --section=NAME
80 generate the documentation only for the given section. Can be
81 used multiple times to specify multiple sections. The supported
82 sections are aliases, bitfields, classes, domains, enums, inter‐
83 faces, structs and unions. Special values are all, meaning all
84 sections (the default); and none, meaning no section
85
86 --dry-run
87 parse the GIR_FILE without generating the documentation
88
89
91 The gen-index command generates an index of symbols and terms that can
92 be used to search inside the documentation generated by gi-docgen.
93
94 gi-docgen gen-index [ OPTIONS ] [ GIR_FILE ]
95
96
97 The generated index is a JSON formatted file is called index.json.
98
99
100 options:
101 --config=FILE
102 use the given project configuration file
103
104 --content-dir=PATH
105 specify the directory where the content files listed in the
106 project configuration file can be found
107
108 --output-dir=PATH
109 create the index under the given directory
110
111 --add-include-path=PATH
112 add a directory to the path which the scanner uses to find GIR
113 files. Can be used multiple times to specify multiple directo‐
114 ries
115
116 --dry-run
117 parse the GIR_FILE without generating the documentation
118
119
121 The check command runs a series of checks on the introspection file, to
122 verify that public API is properly documented. It can be used as part
123 of a test suite.
124
125 gi-docgen check [ OPTIONS ] [ GIR_FILE ]
126
127
128 options:
129 --config=FILE
130 use the given project configuration file
131
132 --add-include-path=PATH
133 add a directory to the path which the scanner uses to find GIR
134 files. Can be used multiple times to specify multiple directo‐
135 ries
136
137
139 The help command prints out the command line help. If you don't specify
140 any command or option when invoking gi-docgen, the help command will be
141 implied.
142
143 gi-docgen help [ OPTIONS ] [ COMMAND ]
144
145
146 If no command is specified, help will print out the list of commands.
147
148 If a command is specified, help will print out the command line help
149 for that program.
150
151
152 options:
153 --version
154 print out the version of gi-docgen
155
156
158 0 The command was successful.
159
160 1 Error, or warning, was generated.
161
162
164 The gi-docgen executable uses the XDG_DATA_DIRS and XDG_DATA_HOME envi‐
165 ronment variables to search for introspection data included in the GIR
166 file.
167
168 If the GIDOCGEN_DEBUG environment variable is set, gi-docgen will print
169 out additional messages, which can be helpful when debugging issues.
170
171
173 GI-DocGen: http://gnome.pages.gitlab.gnome.org/gi-docgen/
174
175 GObject-Introspection: https://gi.readthedocs.org/
176
177 GObject: https://developer.gnome.org/gobject/
178
179
180
181gi-docgen 2021.3 GI-DOCGEN(1)