从GitHub Releases构建sphinx更改日志
项目描述
Sphinx Github Changelog：从GitHub Releases构建sphinx更改日志
Sphinx-github-changelog是一个Sphinx插件，它基于存储库的GitHub Releases内容构建更改日志部分。
如何？(简短版)
在您的Sphinx文档 conf.py
extensions = [
..., # your other extensions
"sphinx_github_changelog",
]
# Provide a GitHub API token:
# Pass the SPHINX_GITHUB_CHANGELOG_TOKEN environment variable to your build
# OR
# You can retrieve your token any other way you want, but of course, please
# don't commit secrets to git, especially on a public repository
sphinx_github_changelog_token = ...在您的文档中
.. changelog::
:changelog-url: https://your-project.readthedocs.io/en/stable/#changelog
:github: https://github.com/you/your-project/releases/
:pypi: https://pypi.ac.cn/project/your-project/在ReadTheDocs上查看此项目的最终结果。
为什么？
在持续交付的道路上，能够轻松发布非常重要。轻松发布的其中一个标准是发布不需要提交和拉取请求。发布拉取请求通常包括两个部分
更改版本
更新更改日志（如果您保留更改日志，让我们假设您这么做）
无提交发布需要一种存储版本和更改日志的方法，尽可能接近代码，但实际上不在代码中。
除了“版本”问题外，sphinx-github-changelog旨在提供一种管理“更改日志”部分的好方法
迄今为止，我们找到的最佳更改日志解决方案是将它存储在GitHub 发布的主体中。这对维护者来说非常实用，但可能不是人们首先寻找它的地方。据我们所见，人们期望更改日志位于
在仓库中，在 CHANGELOG.rst 文件中，
在文档中。
在 CHANGELOG.rst 中放置更改日志会导致一些问题
要么每个 PR 都添加一条单独的更改日志行，但是
你很可能会遇到无数的合并冲突，
更改日志不会告诉你哪些贡献是哪个版本的哪一部分
这降低了整个项目的兴趣。
或者你的更改日志在发布时被编辑。也许你正在使用 towncrier 进行基于片段的更改日志，但你不再进行无提交的发布了。你可以想象发布提交是由你的 CI 完成的，但这样很快就会变得令人烦恼，特别是如果你需要拉取请求的话。
但还有另一种方法。不是提供更改日志，CHANGELOG.rst 文件可以包含更改日志的链接。这使得事情变得容易得多。sphinx-github-changelog鼓励你这样做。
完整的工具包
除了 sphinx-github-changelog 之外，我们建议一些可以很好地一起使用的工具
setuptools-scm 将根据 git 标签在 setup.py 中计算你的版本。
release-drafter 将在将拉取请求合并到你的仓库时更新“草稿发布”，这样你只需要稍微调整发布正文，然后创建一个标签。
任何持续集成解决方案都应该能够监听新标签，并构建上传到 PyPI 的分发。别忘了使用 PyPI API令牌！
当然还有 ReadTheDocs 来托管你的构建文档。
如果你使用上述所有工具，那么发布就像校对草稿 GitHub 发布并按下“发布发布”一样简单。就这样。
参考文档
扩展选项（conf.py）
sphinx_github_changelog_token：GitHub API令牌。如果仓库是公开的，令牌不需要任何特殊访问权限（你可以取消选中所有内容）。如果仓库是私有的，你需要给你的令牌足够的访问权限来读取发布。默认值为环境变量 SPHINX_GITHUB_CHANGELOG_TOKEN 的值。如果没有提供值，构建仍然会通过，但不会构建更改日志，并且会显示（如果提供）changelog-url 链接。
sphinx_github_changelog_root_repo（可选）：仓库的根 URL，默认为“https://github.com/”。如果你在使用自托管的 GitHub 实例，这很有用。
sphinx_github_changelog_graphql_url（可选）：GraphQL API 的 URL，默认为“https://api.github.com/graphql”。如果你在使用自托管的 GitHub 实例，这很有用。
指令
.. changelog::
:changelog-url: https://your-project.readthedocs.io/en/stable/changelog.html
:github: https://github.com/you/your-project/releases/
:pypi: https://pypi.ac.cn/project/your-project/属性
github（必需）：仓库发布页面的 URL。
changelog-url（可选）：你构建的更改日志的 URL。sphinx-github-changelog 将在未提供 GitHub 令牌时显示指向你构建的更改日志的链接（希望这在你的构建文档中不会发生）
pypi（可选）：仓库 PyPI 页面的 URL。这允许更改日志显示指向每个 PyPI 发布的链接。
您会注意到这里每个参数都不是以最简单的形式请求，而是以非常具体的URL请求，程序从这些URL中提取所需信息。这是故意为之的。如果人们浏览您文档的未构建版本（例如在GitHub或PyPI直接），他们仍然会看到包含所需信息的页面链接，而不是无用的指示。
查看构建版本！
此Readme也是作为Sphinx文档构建的，并包含变更日志。想看看它是什么样子吗？请在我们的ReadTheDocs空间查看。
如果您遇到错误，或想联系，您始终欢迎打开问题单。
其他链接
哈希值 for sphinx_github_changelog-1.4.0-py3-none-any.whl
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | cdf2099ea3e4587ae8637be7ba609738bfdeca4bd80c5df6fc45046735ae5c2f |
|
| MD5 | cf7537d1c90ed4196eaa4b89c8cd6341 |
|
| BLAKE2b-256 | 0307a669a23f47803ad12e620b68b761bf7bf32fd9f293c5846fda8f3893d706 |
