构建Ansible文档的工具
项目描述
antsibull-docs -- Ansible 文档构建脚本
用于构建Ansible文档的工具。这主要包括antsibull-docs命令和Sphinx扩展sphinx_antsibull_ext。请参阅文档以获取更多信息。
您可以在antsibull-docs变更日志中找到更改列表。
antsibull-docs遵循Ansible行为准则。
社区
需要帮助或想要讨论项目？请参阅我们的社区指南了解如何加入对话！
版本和兼容性
从版本1.0.0开始，antsibull-docs坚持语义版本控制，旨在在主版本周期内不向命令行API（antsibull-docs）提供破坏性向后兼容的更改。如果存在严重的安全漏洞，我们可能会对此作出例外。
当前主版本为2.x.y。2.x.y的开发在main分支上进行。2.x.y主要区别于1.x.y在于放弃了对Python 3.6、3.7和3.8的支持，以及放弃了对较旧Ansible/ansible-base/ansible-core版本的支持。请参阅变更日志以获取详细信息。1.x.y仍在stable-1分支上开发，但只会回滚安全修复、主要错误修复和其他绝对必要的更改。
我们明确排除了代码兼容性。antsibull-docs不应用作库。唯一的例外是与其他antsibull项目的潜在依赖关系（目前没有）。如果您想将antsibull-docs的某个部分用作库，请创建一个问题，以便我们可以讨论是否为Python代码的某些部分添加稳定的接口。但我们不保证这真的会发生。
如果您对解释Ansible标记的库支持感兴趣，请参阅antsibull-docs-parser项目。
开发
安装并运行nox以运行所有测试。简单的贡献就到这里！nox将在项目检出的.nox内部创建虚拟环境，并安装运行测试所需的依赖项。
antsibull-docs依赖于姐妹antsibull-changelog、antsibull-core、antsibull-docs-parser、antsibull-docutils和antsibull-fileutils项目。默认情况下，nox将从Github安装这些项目的开发版本。如果您在antsibull-docs的同时修改antsibull-changelog、antsibull-core、antsibull-docs-parser、antsibull-docutils和/或antsibull-fileutils，当运行测试时，nox将自动从../antsibull-changelog、../antsibull-core、../antsibull-docs-parser、../antsibull-docutils和../antsibull-fileutils安装项目（如果这些路径存在）。您可以通过OTHER_ANTSIBULL_MODE环境变量更改此行为。
OTHER_ANTSIBULL_MODE=auto— 上文所述的默认行为OTHER_ANTSIBULL_MODE=local— 从../antsibull-changelog、../antsibull-core、../antsibull-docs-parser、../antsibull-docutils和../antsibull-fileutils安装项目。如果这些路径不存在，则失败。OTHER_ANTSIBULL_MODE=git— 从Github主分支安装项目OTHER_ANTSIBULL_MODE=pypi— 从PyPI安装最新版本
运行特定测试
nox -e test仅运行单元测试；nox -e lint运行所有linters和formatter；nox -e codeqa运行flake8、pylint、reuse lint和antsibull-changelog lint；nox -e formatters运行isort和black；nox -e typing运行mypy。
创建更完整的本地开发环境
git clone https://github.com/ansible-community/antsibull-changelog.git
git clone https://github.com/ansible-community/antsibull-core.git
git clone https://github.com/ansible-community/antsibull-docs-parser.git
git clone https://github.com/ansible-community/antsibull-docs.git
git clone https://github.com/ansible-community/antsibull-docutils.git
cd antsibull-docs
python3 -m venv venv
. ./venv/bin/activate
pip install -e '.[dev]' -e ../antsibull-changelog -e ../antsibull-core -e ../antsibull-docs-parser -e ../antsibull-docutils
[...]
nox
更新Sphinx扩展的CSS文件
该CSS文件 sphinx_antsibull_ext/antsibull-minimal.css 由 sphinx_antsibull_ext/css/antsibull-minimal.scss 使用 SASS 和 postcss，并通过 autoprefixer 和 cssnano 构建。
使用位于 sphinx_antsibull_ext/css/ 下的脚本 build.sh 从 .scss 文件构建 .css 文件。
cd sphinx_antsibull_ext/css/
./build-css.sh
为此，您需要安装一些Node.js依赖项。
npm clean-install
创建新版本
- 运行
nox -e bump -- <version> <release_summary_message>。这将- 在
src/antsibull_docs/__init__.py中提升软件包版本。 - 创建包含
release_summary节的changelogs/fragments/<version>.yml。 - 运行
antsibull-changelog release --version <version>并将更改的文件添加到git。 - 提交信息为
发布 <version>并运行git tag -a -m 'antsibull-docs <version>' <version>。 - 运行
hatch build --clean。
- 在
- 运行
git push到相应的远程仓库。 - 一旦GitHub上的CI通过，运行
nox -e publish。这将- 运行
hatch publish； - 将版本提升到
<version>.post0； - 将更改的文件添加到git并运行
git commit -m 'Post-release version bump.'；
- 运行
- 将
git push --follow-tags运行到相应的远程仓库并创建GitHub版本。
许可证
除非代码中有其他说明，否则它遵循GNU通用公共许可证v3的条款，或者根据您的选择，使用更晚的版本。有关许可证副本，请参阅 LICENSES/GPL-3.0-or-later.txt。
该仓库遵循 REUSE规范 以声明版权和许可信息。唯一的例外是位于 changelog/fragments/ 的更改日志片段。
下载文件
下载适合您平台的文件。如果您不确定选择哪个，请了解更多关于 安装包 的信息。
源分发
构建分发
antsibull_docs-2.14.0.tar.gz 的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | b4e40bfb3674fa44834be3eb9d23dd4831cab6a0780c7f1448ac85208e731637 |
|
| MD5 | e8f5d1eaba9710e0af68fc10cf0db342 |
|
| BLAKE2b-256 | 9b39b18003073da5642cae550af11a80fab352dec8752b2aab9da18c0658f79a |
antsibull_docs-2.14.0-py3-none-any.whl 的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 1a302340a3640438e0dc83a9ca385ee6724abe0ee57198736de526046251ac0e |
|
| MD5 | 626dbccd73521b6f2462806fccfef1f0 |
|
| BLAKE2b-256 | 219586be7e782440ee683a2852d76c332c82992fe019c59e39e40bf75a8dabf2 |