sphinxcontrib-towncrier 0.4.0a0

如何使用此工具？

$ pip install sphinxcontrib-towncrier

extensions = ['sphinxcontrib.towncrier.ext']

# 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

确保指向包含 pyproject.toml 的目录，并在配置中预先配置towncrier本身。

如果上述所有设置都正确，您应该可以添加

.. towncrier-draft-entries::

将版本标题添加到您的文档中，例如 changelog.rst。如果没有提供参数，版本标题将使用在 towncrier_draft_autoversion_mode 设置中设置的策略生成。

如果您想控制它，可以使用您喜欢的参数覆盖它。

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

参数中的原生 RST 替换是有效的，只需确保通过 rst_epilog 或在文档末尾（在 towncrier-draft-entries 指令使用的地方）声明任何非默认替换即可。

有人真的使用这个吗？

到目前为止，我们知道有两个项目使用 sphinxcontrib-towncrier —— ansible/pylibssh 和 pypa/pip。此外，这个 Sphinx 扩展受到了 pytest-dev/pytest 和 tox-dev/tox 中使用的一些想法的启发。我们相信，这些项目中充满了您可能希望探索的奇妙技巧，无论您是否会使用我们的项目。