.. SPDX-FileCopyrightText: 2021 GNOME Foundation
..
.. SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
=========
Templates
=========
The `generate` command of gi-docgen uses `Jinja2 `__
templates to generate the HTML pages of the API reference from the
introspection data provided by a library.
Template configuration
----------------------
Each template must contain a template configuration file, with the same name as
the template all in lower case. The template configuration format is ToML.
The template configuration file can contain the following sections:
The ``metadata`` section
~~~~~~~~~~~~~~~~~~~~~~~~
Contains template metadata, like licensing and author information:
``name`` = ``s``
The name of the template
``author_name`` = ``s``
The name of the author of the template
``author_email`` = ``s``
The email of the author of the template
``copyright_year`` = ``s``
The copyright year of the template
``license`` = ``s``
The license of the template, as an `SPDX identifier `__.
The ``templates`` section
~~~~~~~~~~~~~~~~~~~~~~~~~
Contains the template files for each section of the template. If the key is
not present, the default file name is used.
``class`` = ``s``
The class template file. Default: ``class.html``
``interface`` = ``s``
The interface template file. Default: ``interface.html``
``property`` = ``s``
The property template file. Default: ``property.html``
``signal`` = ``s``
The signal template file. Default: ``signal.html``
``method`` = ``s``
The method template file. Default: ``method.html``
``vfunc`` = ``s``
The virtual method template file. Defalt: ``vfunc.html``
``type_func`` = ``s``
The type function template file. Default: ``type_func.html``
``ctor`` = ``s``
The constructor function template file. Default: ``type_func.html``
``class_method`` = ``s``
The class method template file. Default: ``class_method.html``
``error`` = ``s``
The error domain template file. Default: ``error.html``
``flags`` = ``s``
The bitfield template file. Default: ``flags.html``
``enum`` = ``s``
The enumeration template file. Default: ``enum.html``
``record`` = ``s``
The record template file. Default: ``record.html``
``union`` = ``s``
The union template file. Default: ``union.html``
``alias`` = ``s``
The alias template file. Default: ``alias.html``
``function`` = ``s``
The function template file. Default: ``function.html``
``constant`` = ``s``
The constant template file. Default: ``constant.html``
``namespace`` = ``s``
The namespace template file. Default: ``namespace.html``
``content`` = ``s``
The template file for additional content. Default: ``content.html``
The ``css`` section
~~~~~~~~~~~~~~~~~~~
Contains style related data.
``style`` = ``s``
The main CSS file for the template
Th ``extra_files`` section
~~~~~~~~~~~~~~~~~~~~~~~~~~
Contains additional files that must be copied into the output directory
after generating the reference.
``files`` = ``list(s)``
A list of files needed by the template. Each file is relative to the
template's directory.
Template data
-------------
Each Jinja template file will be passed objects and additional data when
gi-docgen renders the API reference.
All templates will receive:
- the ``CONFIG`` object, containing the project configuration
- the ``namespace`` object, containing the GIR namespace
Additionally, each template will receive a template object containing the
information needed to render the template.