.. SPDX-FileCopyrightText: 2021 GNOME Foundation
..
.. SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
=====================
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