Exporting release notes¶

Besides being inserted into the changelog document, the release notes of a version can be exported to another format (typically markdown).

This is particularly useful when publishing release notes in separate places, e.g. GitHub releases.

rtfc supports multiple exporters (see below). The exporter to use must first be configured, e.g. the github-markdown exporter with the sphinx format engine:

rtfc.toml

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

pyproject.toml

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

The export command can then be used to produce the exported release notes:

$ rtfc export github-markdown --version 1.2.0 > release-notes.md

Run the export before rtfc build, which deletes the entry files on release.

Exporters and format engines¶

Exporters are responsible for converting changelog entries (present in your entry directory) into a single text block, that can then be published separately. An exporter is defined for a specific documentation format, and delegates the conversion of the format-specific syntax to a format engine.

A format engine encapsulates the logic required to run your documentation engine/framework. While formats are agnostic of the documentation framework [1], exporters need to use the semantics of your documentation engine, for example to resolve references as HTML links.

rtfc provides hree built in exporters:

markdown: CommonMark output. Admonitions are rendered as block quotes opened by a bold label.
github-markdown: GitHub Flavored Markdown output, extended with the GitHub markdown extensions. Suitable for GitHub releases.
gitlab-markdown: GitLab Flavored Markdown output. Suitable for GitHub releases.

All three support the sphinx format engine.

The sphinx engine¶

The sphinx engine requires Sphinx to be installed, and converts the Sphinx-flavored rst of the entries by building them through the project’s own Sphinx documentation (i.e. by using the project’s Sphinx configuration). Headings, paragraphs, lists, code blocks, inline markup, links, images and admonitions are supported. Other nodes are left as is. Relative links are joined onto the base URL of the published documentation.

rtfc.toml

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

pyproject.toml

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

Note

Each export runs a Sphinx build of the whole project, as resolving cross-references requires the complete environment.

Footnotes