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.