Registry / devops / sphinxcontrib-towncrier

sphinxcontrib-towncrier

JSON →
library0.5.0a0pypypi✓ verified 83d ago

A Sphinx extension that provides an RST directive to inject a Towncrier-generated changelog draft for the unreleased (next) version. Current version 0.5.0a0, requires Python >=3.9. Development is active but the package is still in alpha.

devops
pip install sphinxcontrib-towncrier
github ↗homepage ↗
INSTALL
IMPORT
SIG · SPHINXCONTRIB-TOWN
S
sphinxcontrib-towncrier
devopspythonv0.5.0a0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

setup
✓ from sphinxcontrib.towncrier import setup
✗ from sphinxcontrib.towncrier_ext import setup
The correct module is sphinxcontrib.towncrier, not towncrier_ext.

Add the extension and configure in conf.py. The directive ``.. towncrier-draft`` will then render unreleased changelog entries.

extensions = ['sphinxcontrib.towncrier'] towncrier_source = 'CHANGES.rst' # or .md towncrier_draft = True # include unreleased changes
Debug
Known issues
gotchaThe extension only works with Sphinx's default writer (HTML, LaTeX, etc.). It does not support custom writers that bypass the standard transforms. If you use a custom writer, you may need to manually invoke the directive's logic.
fix
Use the standard Sphinx builders or patch the custom writer to call the directive's run method.
affects: all
deprecatedThe 'towncrier_draft' configuration option is deprecated in favor of setting the directive's :draft: flag directly in the RST file.
fix
Remove 'towncrier_draft' from conf.py and use '.. towncrier-draft:: :draft:' in your RST file.
affects: >=0.5.0a0
gotchaThe directive expects towncrier to be configured and present in the project. If towncrier is missing or misconfigured, the build will fail silently or produce an empty output.
fix
Ensure towncrier is installed and has a valid pyproject.toml / towncrier.toml configuration.
affects: all
breakingVersion 0.5.0a0 dropped support for Python 3.8 and earlier. If your project still uses Python 3.8, pin to the last compatible release (likely 0.4.0).
fix
Upgrade Python to 3.9+ or pin version: pip install 'sphinxcontrib-towncrier<0.5.0a0'
affects: >=0.5.0a0
Errors
Common errors & fixes
WARNING: unknown directive type 'towncrier-draft'.
The extension is not enabled in conf.py.
fix
Add 'sphinxcontrib.towncrier' to the 'extensions' list in conf.py.
sphinxcontrib.towncrier requires towncrier to be installed
Missing towncrier dependency.
fix
pip install towncrier
Directive 'towncrier-draft' requires the project to have towncrier configured
No towncrier configuration found (pyproject.toml or towncrier.toml).
fix
Create a towncrier configuration file (e.g., towncrier.toml) with a [tool.towncrier] section.
Upgrade
Version history
0.5.0a0latest on PyPI · released Feb 28, 2025
Audit
Dependencies
towncrierrequiredRequired to generate the changelog fragments.
Agent activity
9 hits · last 30 days
node
8
Resources
githubhttps://github.com/sphinx-contrib/sphinxcontrib-towncrier ↗
homepagehttps://github.com/sphinx-contrib/sphinxcontrib-towncrier ↗
sphinxcontrib-towncrier — pip install sphinxcontrib-towncrier · libregistry