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=sThe name of the template
author_name=sThe name of the author of the template
author_email=sThe email of the author of the template
copyright_year=sThe copyright year of the template
license=sThe 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=sThe class template file. Default:
class.htmlinterface=sThe interface template file. Default:
interface.htmlproperty=sThe property template file. Default:
property.htmlsignal=sThe signal template file. Default:
signal.htmlmethod=sThe method template file. Default:
method.htmlvfunc=sThe virtual method template file. Defalt:
vfunc.htmltype_func=sThe type function template file. Default:
type_func.htmlctor=sThe constructor function template file. Default:
type_func.htmlclass_method=sThe class method template file. Default:
class_method.htmlerror=sThe error domain template file. Default:
error.htmlflags=sThe bitfield template file. Default:
flags.htmlenum=sThe enumeration template file. Default:
enum.htmlrecord=sThe record template file. Default:
record.htmlunion=sThe union template file. Default:
union.htmlalias=sThe alias template file. Default:
alias.htmlfunction=sThe function template file. Default:
function.htmlconstant=sThe constant template file. Default:
constant.htmlnamespace=sThe namespace template file. Default:
namespace.htmlcontent=sThe template file for additional content. Default:
content.html
The css section
Contains style related data.
style=sThe 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
CONFIGobject, containing the project configurationthe
namespaceobject, containing the GIR namespace
Additionally, each template will receive a template object containing the information needed to render the template.