gi-docgen(1)

1
2
3GI-DOCGEN(1)                     User Commands                    GI-DOCGEN(1)
4
5
6

NAME

8       gi-docgen - a documentation generator using gobject-introspection
9

SYNOPSIS

11       gi-docgen COMMAND [OPTION...] GIR_FILE
12

DESCRIPTION

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

Common options

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

The generate command

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

The gen-index command

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

The check command

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

The serve command

139       The  serve command generates an API reference and serves it using a lo‐
140       cal HTTP server.
141
142       gi-docgen serve [ OPTIONS ] [ GIR_FILE ]
143
144
145       The serve command will parse the given GIR file, as well as its  depen‐
146       dencies,  and  build an API reference for the namespace it finds in the
147       introspection data. Once the reference  has  been  built  successfully,
148       gi-docgen  will start a local HTTP server pointing at the output direc‐
149       tory.
150
151
152   options:
153       --bind=ADDRESS
154              use the given address  for  the  HTTP  server;  the  default  is
155              127.0.0.1
156
157       --port=PORT
158              use the given port for the HTTP server; the default is 8080
159
160

The help command

162       The help command prints out the command line help. If you don't specify
163       any command or option when invoking gi-docgen, the help command will be
164       implied.
165
166       gi-docgen help [ OPTIONS ] [ COMMAND ]
167
168
169       If no command is specified, help will print out the list of commands.
170
171       If  a  command  is specified, help will print out the command line help
172       for that program.
173
174
175   options:
176       --version
177              print out the version of gi-docgen
178
179

EXIT STATUS

181       0      The command was successful.
182
183       1      Error, or warning, was generated.
184
185

ENVIRONMENT VARIABLES

187       The gi-docgen executable uses the XDG_DATA_DIRS and XDG_DATA_HOME envi‐
188       ronment  variables to search for introspection data included in the GIR
189       file.
190
191       If the GIDOCGEN_DEBUG environment variable is set, gi-docgen will print
192       out additional messages, which can be helpful when debugging issues.
193
194