gi-docgen - Man Page

a documentation generator using gobject-introspection

Synopsis

gi-docgen COMMAND [OPTION...] GIR_FILE

Description

GI-DocGen is a document generator for GObject-based libraries. GObject is the base type system of the GNOME project. GI-DocGen uses the machine readable introspection data provided by GObject-based libraries in order to generate the API reference of these libraries, as well as other ancillary documentation.

The main gi-docgen executable provides various subcommands to access all its functionality.

Common options

All commands have the following options:

--quiet

do not print details of the current operation

--fatal-warnings

make warnings fatal errors

--help

print command line help

The generate command

The generate command provides the main functionality of gi-docgen.

gi-docgen generate [ OPTIONS ] [ GIR_FILE ]

The generate command will parse the given GIR file, as well as its dependencies, and build an API reference for the namespace it finds in the introspection data. Projects can use a configuration file to control aspects of the output, as well as provide additional content that should be included in the documentation.

options

--config=FILE

use the given project configuration file

--content-dir=PATH

specify the directory where the content files listed in the project configuration file can be found

--templates-dir=PATH

specify the directory where the templates used to generate the documentation can be found

--theme-name=NAME

specify the template name to be used when generating the documentation, overriding the project's configuration

--output-dir=PATH

create the documentation under the given directory

--no-namespace-dir

generate all documentation files directly under the output directory, instead of creating a directory using the namespace name and version

--add-include-path=PATH

add a directory to the path which the scanner uses to find GIR files. Can be used multiple times to specify multiple directories

--section=NAME

generate the documentation only for the given section. Can be used multiple times to specify multiple sections. The supported sections are aliases, bitfields, classes, domains, enums, interfaces, structs and unions. Special values are all, meaning all sections (the default); and none, meaning no section

--dry-run

parse the GIR_FILE without generating the documentation

The gen-index command

The gen-index command generates an index of symbols and terms that can be used to search inside the documentation generated by gi-docgen.

gi-docgen gen-index [ OPTIONS ] [ GIR_FILE ]

The generated index is a JSON formatted file is called index.json.

options

--config=FILE

use the given project configuration file

--content-dir=PATH

specify the directory where the content files listed in the project configuration file can be found

--output-dir=PATH

create the index under the given directory

--add-include-path=PATH

add a directory to the path which the scanner uses to find GIR files. Can be used multiple times to specify multiple directories

--dry-run

parse the GIR_FILE without generating the documentation

The check command

The check command runs a series of checks on the introspection file, to verify that public API is properly documented. It can be used as part of a test suite.

gi-docgen check [ OPTIONS ] [ GIR_FILE ]

options

--config=FILE

use the given project configuration file

--add-include-path=PATH

add a directory to the path which the scanner uses to find GIR files. Can be used multiple times to specify multiple directories

The help command

The help command prints out the command line help. If you don't specify any command or option when invoking gi-docgen, the help command will be implied.

gi-docgen help [ OPTIONS ] [ COMMAND ]

If no command is specified, help will print out the list of commands.

If a command is specified, help will print out the command line help for that program.

options

--version

print out the version of gi-docgen

Exit Status

0

The command was successful.

1

Error, or warning, was generated.

Environment Variables

The gi-docgen executable uses the XDG_DATA_DIRS and XDG_DATA_HOME environment variables to search for introspection data included in the GIR file.

If the GIDOCGEN_DEBUG environment variable is set, gi-docgen will print out additional messages, which can be helpful when debugging issues.

See Also

GI-DocGen: http://gnome.pages.gitlab.gnome.org/gi-docgen/

GObject-Introspection: https://gi.readthedocs.org/

GObject: https://developer.gnome.org/gobject/

Info

gi-docgen 2021.3