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 level 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:: :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
Sphinx_Changelog 1.2.1.dev5+g441f8cd (2023-03-01)¶
towncrierversion is now pinned to a specific version in
This release pins the version of towncrier to 22.12.0, this is because we rely on private API in towncrier, so changes are needed on every release.
Update to towncrier 22.12.0, and other fixes by @dstansby in https://github.com/OpenAstronomy/sphinx-changelog/pull/17
Migrate to github actions by @Cadair in https://github.com/OpenAstronomy/sphinx-changelog/pull/18
@dstansby made their first contribution in https://github.com/OpenAstronomy/sphinx-changelog/pull/17
This release requires towncrier 22.8.0
docs: Fix typo in level by @jmartens in https://github.com/OpenAstronomy/sphinx-changelog/pull/13
Fix for removed top_line argument in towncrier renderer by @ConorMacBride in https://github.com/OpenAstronomy/sphinx-changelog/pull/14
@jmartens made their first contribution in https://github.com/OpenAstronomy/sphinx-changelog/pull/13
@ConorMacBride made their first contribution in https://github.com/OpenAstronomy/sphinx-changelog/pull/14
Full Changelog: https://github.com/OpenAstronomy/sphinx-changelog/compare/v1.1.2…v1.2.0
Sphinx_Changelog v1.1.2 (2021-08-19)¶
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)¶
: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)¶
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)¶
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)¶
Add a flag to skip running towncrier if no fragment files are found. (#6)
Fix resolving paths relative to the file containing the changelog directive. (#6)
Sphinx_Changelog v0.1rc3 (2021-03-02)¶
Raise a more helpful error if no towncrier config can be found. (#5)
Sphinx_Changelog v0.1rc2 (2021-03-01)¶
Implement options for changelog backend. Including the existing changelog and towncrier are currently available. (#1)
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.