sphinx-changelog Documentation

Sphinx changelog is a sphinx extension to render changelogs into your documentation. Currently it supports rendering towncrier changelogs.

To use it first put the following into your conf.py file to enable the extension:

extensions = [
    ...
    'sphinx_changelog'
]

then put the following rst into your documentation:

.. changelog::
   :towncrier:

By default it will assume the root of the repository (location of the pyproject.toml file) is up one leve from the location of the rst file with the directive in it. This makes the default equivalent to:

.. changelog::
   :towncrier: ../

The path should point to the root of the repository from the location of the file with the directive in it.

If you want to include the rendered changelog as well as the development one rendered by towncrier you can add the :changelog_file: option:

.. changelog::
   :towncrier: ../
   :changelog_file: ../CHANGELOG.rst

The changelog file is assumed to be an ReST file, and will be included below the towncrier output. It is possible to use just the changelog include and not towncrier.

Skipping towncrier on Release Builds

If you combine the towncrier and changelog file options, when the documentation builds on a release there will be no fragments to render. This means that towncrier will still render an empty changelog duplicating the pre-rendered header for the release. To disable towncrier output if no fragment files are found add the :towncrier-skip-if-emtpy: option to the directive:

.. changelog::
   :towncrier: ../
   :towncrier-skip-if-empty:
   :changelog_file: ../CHANGELOG.rst

Controlling the Underline Used by towncrier

When embedding the directive in an existing rst document you might need to adjust the heading levels used when rendering the changelog. towncrier provides the “underlines” config option which allows you to control the characters used. By default the 0th element in this sequence is used for the title and the following ones for the subsections. This behaviour can be adjusted by setting the towncrier-title-underline-index option as follows:

.. changelog::
   :towncrier: ../
   :towncrier-title-underline-index: 1

Note that this setting does not affect the rendered changelog, so it is probably not very useful when combined with the :changelog_file: option.

sphinx-changelog’s Changelog

Sphinx_Changelog 1.1.2 (2021-08-19)

No significant changes.

Sphinx_Changelog v1.1.2 (2021-08-19)

Bug Fixes

  • Explicitly specify encoding when writing changelog. (#11)

  • Fixed rendering to match towncrier, which means that top_line should not be included in the template. (#12)

Sphinx_Changelog v1.1.1 (2021-05-14)

Bug Fixes

  • Re-implement the :towncrier-skip-if-empty: flag as it was dropped in the upgrade to 21.3. (#10)

Sphinx_Changelog v1.1.0 (2021-05-11)

No significant changes.

Sphinx_Changelog 1.1.0rc1 (2021-05-11)

Features

  • Update to support only the latest release of towncrier as there were some substantial changes. (#9)

  • Added support for controlling the title underline used by towncrier in the changelog directive. (#9)

Sphinx_Changelog v1.0.0 (2021-03-16)

No significant changes.

Sphinx_Changelog v0.1rc5 (2021-03-03)

Bug Fixes

  • Do not raise exceptions inside the directive as this can cause the sphinx parallel build to fail. (#8)

Sphinx_Changelog v0.1rc4 (2021-03-02)

Features

  • Add a flag to skip running towncrier if no fragment files are found. (#6)

Bug Fixes

  • Fix resolving paths relative to the file containing the changelog directive. (#6)

Sphinx_Changelog v0.1rc3 (2021-03-02)

Bug Fixes

  • Raise a more helpful error if no towncrier config can be found. (#5)

Sphinx_Changelog v0.1rc2 (2021-03-01)

Features

  • Implement options for changelog backend. Including the existing changelog and towncrier are currently available. (#1)

Bug Fixes

  • Fix use of template and update to parsing code from a newer towncrier version (#3)

Sphinx_Changelog v0.1rc1 (2021-03-01)

Initial implementation copied from sunpy.