Project configuration — gi-docgen

# 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/’ ],

  ]

## 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