Project configuration

Projects using gi-docgen should provide their own configuration file to describe how to generate their API reference.

The configuration file format uses ToML to provide key and value pairs that will be used by gi-docgen and, optionally, by the templates themselves.

Project configuration takes precendence over gi-docgen’s defaults, but can be overridden by command line options, where applicable.

Standard sections and keys

The `library` section

The library section is used to define the library configuration values that gi-docgen will pass to the templates, as well as configuration switches that control the files generated by gi-docgen.

The following keys are used, if found:

version = s: The version of the library. This is the actual version of the shared library, as opposed to the version of the API as represented by the namespace.
authors = s: The name of the authors of the library, as a string.
license = s: The license of the documentation, as an SPDX identifier.
website_url = s: The website for the library.
browse_url = s: The website that can be used to browse the source code of the library.
logo_url = s: The location of a logo image. This can be a local file, or a URL.
description = s: A short description of the library.
dependencies = dict(s, dict(s, s)): A dictionary of dependencies; each entry in the dictionary has a key in the form of {namespace}-{version}, and values in the form of a dictionary with the following keys: name, description, and docs_url. Each entry in the this dictionary can only describe a namespace included in the introspection data; any other namespace listed here will be ignored. See the related configuration below.
related = dict(s, dict(s, s)): A dictionary of related namespaces; each entry in the dictionary has a key in the form of {namespace}-{version}, and values in the form of a dictionary with the following keys: name, description, and docs_url. Each entry in this dictionary can describe a namespace that is related to the project.
devhelp = b: Whether gi-docgen should generate a DevHelp file for the namespace.
search_index = b: Whether gi-docgen should generate a search index file for the namespace.
docs_url = s: The website that will provide this documentation.

The `theme` section

The theme section is used to define the theme being used by gi-docgen when generating the API reference of a project.

The following keys are used, if found:

templates_dir = s: The directory that contains the templates to be used by gi-docgen. The default directory is inside the gi-docgen module directory. This key can be overridden by the --templates-dir command line argument.
name = s: The name of the template to use. The name is a sub-directory of the template_dir directory, and will be used to load the template’s configuration file. This key can be overridden by the --theme-name command line argument.
show_index_summary = b: A boolean value that controls whether to show the summary of each symbol in the namespace index.
show_class_hierarchy = b: A boolean value that controls whether to generate a class graph with the ancestors of a type, as well as the implemented interfaces. Requires the dot utility from GraphViz installed in the PATH.

The `source-location` section

The source-location section is used to define the location of the source code repository of a project to allow gi-docgen to create links from the API reference to the definition of symbols and the source of the documentation stanzas.

The following keys are used, if found:

base_url = s: The base URL for accessing a file in the source code repository.
file_format = s: The format string used to point to a file, and a line in that file; the string can contain the token {filename}, which will be replaced with the basename of the file; and the token {line}, which will be replaced with the line in the file. The default value for this key is: {filename}#L{line}.

The `extra` section

The extra section is used to define additional content used when generating the API reference of a project.

The following keys are used, if found:

content_files = list(s)

A list of tuples. The first element of the tuple is a Markdown file name, relative to the directories specified by the --content-dir command line arguments; the second element of the tuple is the title used for the link to the content file. When generating the API reference, gi-docgen will transform the Markdown file into an HTML one, using the same pre-processing filters applied to the documentation blocks found in the introspection data. The generated HTML files will be placed in the root directory of the namespace.

content_images = list(s)

A list of files, relative to the directories specified by the --content-dir command line arguments. The files will be copied in the root directory of the namespace.

Any image whose filename starts with favicon will be used as a favicon. Icons whose name ends in {size}x{size}.png for sizes in 32, 128, 180 (iOS), and 192 (Android) will be special cased.

content_base_url = s

The base URL for accessing a content file in the source code repository. The final URL will use the base name of the content file. You can use the origin field in the content metadata to control the base name of the file when generating the URL.

urlmap_file = s

Path of a JavaScript file that defines the mapping from namespaces to url prefixes for resolving links to external symbols, as a JavaScript map with the name baseURLs:

::

# SPDX-FileCopyrightText: 2023 Your Name Here # SPDX-License-Identifier: CC0-1.0

baseURLs = [: [ ‘Pango’, ‘https://gnome.pages.gitlab.gnome.org/pango/Pango/’ ], [ ‘PangoCairo’, ‘https://gnome.pages.gitlab.gnome.org/pango/PangoCairo/’ ],

]

The `check` section

The check section is used to define the behavior of the gi-docgen check command.

The following keys are used, if found:

ignore_deprecated = b: A boolean value that controls whether to skip deprecated types and symbols when checking documentation blocks. It is set to false by default.

Symbol overrides

Visibility

It is possible to override the visibility of types, properties, and symbols in the introspection data from within the project configuration file.

The following example will hide the type Protected:

[[object]]
name = "Protected"
hidden = true

The type will be skipped when generating the API reference and the search index. This annotation applies to all possible top-level types:

aliases

bitfields

callbacks

classes

domains

enums

functions

function macros

interfaces

records

unions

The object key is always an array of dictionaries; each element in the array can have a name key, used to match the object name exactly; or a pattern key, which uses a regular expression to match the object name.

Each object can contain the following keys:

name: the name of the symbol to match exactly

pattern: a regular expression to match the symbol name

hidden: whether the symbol should be hidden from the documentation

check_ignore: whether the symbol should be skipped when checking the documentation

Each element can also have the following sections:

property

signal

constructor

method

function

Each one of these sections can contain array of objects.

The following example will hide the backend property on the Printer type:

[[object]]
name = "Printer"

  [[object.property]]
  name = "backend"
  hidden = true

The following example will hide the private-changed signal on the StyleProvider type:

[[object]]
name = "StyleProvider"

  [[object.signal]]
  name = "private-changed"
  hidden = true

The following example will skip the quark function on the ParserError type when checking the documentation:

[[object]]
name = "ParserError"

  [[object.function]]
  name = "quark"
  check_ignore = true

Project configuration

Standard sections and keys

The library section

The theme section

The source-location section

The extra section

The check section

Symbol overrides

Visibility

The `library` section

The `theme` section

The `source-location` section

The `extra` section

The `check` section