Sphinx extension

rtfc ships a sphinx extension rendering the unreleased changelog entries in the built documentation. Entries not yet released only exist as files in the entry directory, and the extension injects them at build time, so the changelog page always previews the upcoming changes without the source file ever being modified.

Setup

Enable the extension in conf.py, and point it at the directory the rtfc configuration lives in:

extensions = ["rtfc.sphinx"]
rtfc_config_directory = "../.."

rtfc_config_directory

Type:

string

Default:

"."

The directory the rtfc Configuration is discovered in, relative to the conf.py directory.

Usage

.. rtfc-unreleased::

Renders the unreleased changelog entries under an Unreleased heading, grouped and sorted according to the Configuration. Renders nothing when there are no entries.

The directive content, when given, is rendered as a note admonition below the heading.

Use the directive where the unreleased changes should appear, typically right above the insert marker:

Changelog
=========

.. rtfc-unreleased::

   These changes are not yet released and are under active development.

.. rtfc-insert