s0undt3ch / sphinxcontrib-towncrier

An RST directive for injecting a Towncrier-generated changelog draft containing fragments for the unreleased (next) project version. Demo: https://ansible-pylibssh.rtfd.io/changelog

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

sphinxcontrib-towncrier @ PyPI GitHub Actions CI/CD build status — Python package Documentation Status @ RTD

sphinxcontrib-towncrier

An RST directive for injecting a Towncrier-generated changelog draft containing fragments for the unreleased (next) project version.

How to use this?

$ pip install sphinxcontrib-towncrier
extensions = ['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 cwd

Make 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

.. towncrier-draft-entries::

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:

.. towncrier-draft-entries:: |release| [UNRELEASED DRAFT]

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.

Does anybody actually use this?

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.

ezoic increase your site revenue

About

An RST directive for injecting a Towncrier-generated changelog draft containing fragments for the unreleased (next) project version. Demo: https://ansible-pylibssh.rtfd.io/changelog

License:BSD 3-Clause "New" or "Revised" License


Languages

Language:Python 100.0%