.. 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 <https://toml.io/en/>`__ 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 <https://spdx.org/licenses/>`__.

``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 <https://graphviz.org/>`__
  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
