sphinxcontrib-towncrier

What it is and what it does

sphinxcontrib-towncrier is a Sphinx extension that bridges Sphinx documentation builds with Towncrier, a changelog management tool. It provides an RST directive that automatically renders a draft changelog containing unreleased fragments into your documentation. The extension reads your project's towncrier configuration and injects the generated changelog at build time, allowing you to display work-in-progress release notes alongside your main documentation.

The package has two runtime dependencies: sphinx and towncrier. It supports Python 3.9 through 3.13 and is classified as alpha-stage software. The extension offers configurable version title generation modes (draft, sphinx-version, or sphinx-release) and allows you to override the title with custom text. It's used by projects like ansible/pylibssh and pypa/pip to keep changelog drafts visible during documentation builds.

Use it for:

• Display unreleased changelog fragments in your project's documentation site during development.
• Automatically generate a draft release notes section in Sphinx docs without manual maintenance.
• Keep contributors and users informed of upcoming changes by embedding the towncrier draft in your docs.
• Integrate changelog management into your Sphinx build pipeline for single-source documentation.
• Override auto-generated version titles with custom release labels or status markers in the changelog.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Sphinx extension that automatically injects a Towncrier-generated changelog draft into documentation, displaying unreleased project version fragments.

Yes, if you use both Sphinx and Towncrier for your project. The extension solves a real integration gap and is actively maintained. However, note that it is still alpha-stage software (version 0.5.0a0), so expect potential API changes. Install it when you want unreleased changelog fragments visible in your documentation builds without manual duplication.

Install

sphinxcontrib-towncrier on PyPI

pip install sphinxcontrib-towncrier

uv add sphinxcontrib-towncrier

poetry add sphinxcontrib-towncrier

Installing sphinxcontrib-towncrier

Before you install

Low install friction with only two runtime dependencies (sphinx and towncrier). Actively maintained with a recent release in February 2025 and ongoing repository activity.

License in practice

BSD 3-Clause License is permissive, allowing commercial and private use with minimal restrictions beyond attribution and liability disclaimers.

Quickstart

pip install sphinxcontrib-towncrier

# In conf.py:
extensions = ['sphinxcontrib.towncrier.ext']
towncrier_draft_autoversion_mode = 'draft'
towncrier_draft_working_directory = PROJECT_ROOT_DIR

# In changelog.rst:
.. towncrier-draft-entries::

Requires towncrier to be pre-configured in your project's pyproject.toml; the extension reads towncrier's configuration from that file.

Verify before relying

• Whether the alpha version (0.5.0a0) is stable enough for production documentation builds.
• Performance characteristics when handling large numbers of changelog fragments.
• Compatibility with custom towncrier fragment types beyond the defaults.

Package facts

Evidence: sphinxcontrib_towncrier-0.5.0a0-py3-none-any.whl

Tags

More Utilities packages