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 help command

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

EXIT STATUS

158       0      The command was successful.
159
160       1      Error, or warning, was generated.
161
162

ENVIRONMENT VARIABLES

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