Commit d44e991f authored by Emmanuele Bassi's avatar Emmanuele Bassi
Browse files

Add a man page for gi-docgen

parent 0fcd344c
Pipeline #268726 passed with stage
in 4 minutes and 45 seconds
\" SPDX-FileCopyrightText: 2021 GNOME Foundation
\" SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
.TH GI\-DOCGEN "1" "" "gi-docgen 2021.3" "User Commands"
.SH NAME
gi-docgen - a documentation generator using gobject\-introspection
.SH SYNOPSIS
.sp
\fBgi\-docgen\fP COMMAND [OPTION...] GIR_FILE
.SH DESCRIPTION
.sp
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.
.sp
The main gi\-docgen executable provides various subcommands to access all
its functionality.
.SH Common options
.sp
All commands have the following options:
.TP
.B \-\-quiet
do not print details of the current operation
.TP
.B \-\-fatal\-warnings
make warnings fatal errors
.TP
.B \-\-help
print command line help
.SH The generate command
.sp
The \fBgenerate\fR command provides the main functionality of gi\-docgen.
.B gi-docgen generate [
.I OPTIONS
.B ] [
.I GIR_FILE
.B ]
.sp
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.
.SS "options:"
.TP
.BI \-\-config\fB= FILE
use the given project configuration file
.TP
.BI \-\-content\-dir\fB= PATH
specify the directory where the content files listed in the project
configuration file can be found
.TP
.BI \-\-templates\-dir\fB= PATH
specify the directory where the templates used to generate the
documentation can be found
.TP
.BI \-\-theme\-name\fB= NAME
specify the template name to be used when generating the documentation,
overriding the project's configuration
.TP
.BI \-\-output\-dir\fB= PATH
create the documentation under the given directory
.TP
.B \-\-no\-namespace\-dir
generate all documentation files directly under the output directory,
instead of creating a directory using the namespace name and version
.TP
.BI \-\-add\-include\-path\fB= PATH
add a directory to the path which the scanner uses to find GIR files. Can
be used multiple times to specify multiple directories
.TP
.BI \-\-section\fB= NAME
generate the documentation only for the given section. Can be used
multiple times to specify multiple sections. Special values are \fIall\fR,
meaning all sections (the default); and \fInone\fR, meaning no section
.TP
.B \-\-dry\-run
parse the \fIGIR_FILE\fR without generating the documentation
.SH The gen-index command
.sp
The \fBgen-index\fR command generates an index of symbols and terms
that can be used to search inside the documentation generated by
gi\-docgen.
.B gi-docgen gen-index [
.I OPTIONS
.B ] [
.I GIR_FILE
.B ]
.sp
The generated index is a JSON formatted file is called \fIindex.json\fR.
.SS "options:"
.TP
.BI \-\-config\fB= FILE
use the given project configuration file
.TP
.BI \-\-content\-dir\fB= PATH
specify the directory where the content files listed in the project
configuration file can be found
.TP
.BI \-\-output\-dir\fB= PATH
create the index under the given directory
.TP
.BI \-\-add\-include\-path\fB= PATH
add a directory to the path which the scanner uses to find GIR files. Can
be used multiple times to specify multiple directories
.TP
.B \-\-dry\-run
parse the \fIGIR_FILE\fR without generating the documentation
.SH The help command
.sp
The \fBhelp\fR 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.
.B gi-docgen help [
.I OPTIONS
.B ] [
.I COMMAND
.B ]
.sp
If no command is specified, help will print out the list of commands.
.sp
If a command is specified, help will print out the command line help for
that program.
.SS "options:"
.TP
.B \-\-version
print out the version of gi\-docgen
.SH EXIT STATUS
.TP
.B 0
The command was successful.
.TP
.B 1
Error, or warning, was generated.
.SH ENVIRONMENT VARIABLES
.sp
The gi\-docgen executable uses the \fBXDG_DATA_DIRS\fP and \fBXDG_DATA_HOME\fP
environment variables to search for introspection data included in the GIR
file.
.sp
If the \fBGIDOCGEN_DEBUG\fP environment variable is set, gi\-docgen will print
out additional messages, which can be helpful when debugging issues.
.SH SEE ALSO
.sp
GI\-DocGen: http://ebassi.gitlab.gnome.org/gi-docgen/
.sp
GObject\-Introspection: https://gi.readthedocs.org/
.sp
GObject: https://developer.gnome.org/gobject/
......@@ -53,6 +53,11 @@ package_data = {
],
}
data_files = [
('share/pkgconfig', ['gi-docgen.pc']),
('share/man/man1', ['gi-docgen.1']),
]
if __name__ == '__main__':
setup(
cmdclass={
......@@ -67,5 +72,5 @@ if __name__ == '__main__':
packages=packages,
package_data=package_data,
entry_points=entries,
data_files=[('share/pkgconfig', ['gi-docgen.pc'])],
data_files=data_files,
)
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment