An RST directive for injecting a Towncrier-generated changelog draft containing fragments for the unreleased (next) project version.
$ pip install sphinxcontrib-towncrierextensions = ['sphinxcontrib.towncrier']
# Options: draft/sphinx-version/sphinx-release
towncrier_draft_autoversion_mode = 'draft'
towncrier_draft_include_empty = True
towncrier_draft_working_directory = PROJECT_ROOT_DIR
# Not yet supported:
# towncrier_draft_config_path = 'pyproject.toml' # relative to cwdMake sure to point to the dir with pyproject.toml and pre-configure towncrier itself in the config.
If everything above is set up correctly, you should be able to add
to your documents, like changelog.rst. With no argument, the version title will be generated using the strategy set up in the towncrier_draft_autoversion_mode setting.
If you want to be in control, override it with an argument you like:
Native RST substitutions in the argument work, just make sure to declare any non-default ones via rst_epilog or at the end of the document where the towncrier-draft-entries directive is being used.
So far we know about two projects using sphinxcontrib-towncrier — ansible/pylibssh and pypa/pip. Also, this Sphinx extension is inspired by and somewhat based on the ideas used in pytest-dev/pytest and tox-dev/tox. We believe that these projects are full of wonderful tricks that you may want to explore regardless of whether you'll use our project.