Configuration

rtfc is configured in TOML, either in the [rtfc] table of an rtfc.toml file or in the [tool.rtfc] table of pyproject.toml (see Usage). Each example below is given for both files. Relative paths are resolved against the directory the configuration is discovered in.

changelog
Type:
path

The changelog file the release notes are inserted into on release. Required; the file must exist and contain the insert marker comment (.. rtfc-insert for the rst format).

[rtfc]
changelog = "docs/source/changelog.rst"

[tool.rtfc]
changelog = "docs/source/changelog.rst"
directory
Type:
path
Default:
"changelog"

The directory holding the changelog entry files. It must exist.

[rtfc]
directory = "changelog.d"

[tool.rtfc]
directory = "changelog.d"
format
Type:
string
Default:
"rst"

The documentation format of the entries and the changelog. rst is built in; third-party formats are looked up in the rtfc.formats entry point group.

[rtfc]
format = "rst"

[tool.rtfc]
format = "rst"
sections
Type:
list
Default:
the change, feature and bugfix sections

The changelog sections (entry categories), in output order. Each item is either a section id (its label is then derived from the id) or a table with id and label keys.

[rtfc]
sections = [
    "deprecation",
    { id = "bugfix", label = "Bug fixes" },
]

[tool.rtfc]
sections = [
    "deprecation",
    { id = "bugfix", label = "Bug fixes" },
]
metadata
Type:
table
Default:
empty (metadata is free-form)

The schema of the entry metadata fields, one table per field. Once a schema is defined, unknown metadata fields are rejected. Each field is configured with:

type

The type of the field value: "string", "integer", "boolean", "number", "date" or "array".

items

The type of the array items. Required (and only allowed) when type is "array".

required

Whether the field must be present on every entry (defaults to false). Mutually exclusive with default.

default

The value applied when the field is absent. Mutually exclusive with required

[rtfc.metadata.gh_issue]
type = "integer"
required = true

[rtfc.metadata.contributors]
type = "array"
items = "string"
default = []

[tool.rtfc.metadata.gh_issue]
type = "integer"
required = true

[tool.rtfc.metadata.contributors]
type = "array"
items = "string"
default = []
render.template
Type:
string
Default:
the template below

The Jinja template rendering the whole release notes of a version. The template receives:

header

The already-formatted version header.

entries

All the entries of the release notes.

sections

The entries grouped by section: the unsectioned group first, then the configured sections in order. Each group has id, label (None for the unsectioned group) and entries attributes.

render_entry(), list_item(), section_header()

Functions rendering an entry through render.entry_template, wrapping text as a list item, and formatting a section heading.

The sort_entries() filter sorts entries by the given keys: date (the default), nonce, or metadata.<field>. Entries missing a value sorting last. The default template renders each non-empty section under its heading, entries sorted by date:

{{ header }}
{% for section in sections if section.entries %}

{% if section.label %}
{{ section_header(section.label) }}

{% endif %}
{% for entry in section.entries | sort_entries %}
{{ list_item(render_entry(entry)) }}
{% endfor %}
{% endfor %}

For example, ignoring sections and rendering a single flat list:

[rtfc.render]
template = """
{{ header }}

{% for entry in entries | sort_entries %}
{{ list_item(render_entry(entry)) }}
{% endfor %}
"""

[tool.rtfc.render]
template = """
{{ header }}

{% for entry in entries | sort_entries %}
{{ list_item(render_entry(entry)) }}
{% endfor %}
"""
render.template_file
Type:
path
Default:
unset

A file containing the release notes template, as an alternative to render.template.

[rtfc.render]
template_file = "version.rst.jinja"

[tool.rtfc.render]
template_file = "version.rst.jinja"
render.entry_template
Type:
string
Default:
"{{ content }}"

The Jinja template rendering a single entry, receiving content, date, nonce, section and metadata in context. Mutually exclusive with render.entry_template_file.

[rtfc.render]
entry_template = "{{ content }}{% if metadata.gh_issue %} (:gh:`{{ metadata.gh_issue }}`){% endif %}"

[tool.rtfc.render]
entry_template = "{{ content }}{% if metadata.gh_issue %} (:gh:`{{ metadata.gh_issue }}`){% endif %}"
render.entry_template_file
Type:
path
Default:
unset

A file containing the entry template, as an alternative to render.entry_template.

[rtfc.render]
entry_template_file = "entry.rst.jinja"

[tool.rtfc.render]
entry_template_file = "entry.rst.jinja"
export.<exporter>.engine
Type:
table

Exporters, converting the release notes to another format, are configured with one table per exporter id. The engine table selects and configures the format engine used to convert the format-specific syntax of the entries; its name key discriminates the engine and its remaining keys. The built-in markdown, github-markdown and gitlab-markdown exporters all support the sphinx engine.

[rtfc.export.markdown.engine]
name = "sphinx"
sphinx_directory = "docs/source"

[tool.rtfc.export.markdown.engine]
name = "sphinx"
sphinx_directory = "docs/source"
export.<exporter>.engine.sphinx_directory
Type:
path

The Sphinx source directory (containing conf.py). Required.

export.<exporter>.engine.base_url
Type:
string
Default:
the html_baseurl Sphinx configuration value

Absolute URL of the published documentation, used to resolve relative links.

[rtfc.export.markdown.engine]
name = "sphinx"
sphinx_directory = "docs/source"
base_url = "https://rtfc.readthedocs.io/en/latest"

[tool.rtfc.export.markdown.engine]
name = "sphinx"
sphinx_directory = "docs/source"
base_url = "https://rtfc.readthedocs.io/en/latest"

See also

The sphinx extension has its own configuration value, rtfc_config_directory, defined in conf.py.