跳转到主要内容

构建Ansible文档的工具

项目描述

antsibull-docs -- Ansible 文档构建脚本

Discuss on Matrix at #antsibull:ansible.com Discuss on Matrix at #docs:ansible.com Nox badge Build docs testing badge Build CSS testing badge Codecov badge REUSE status

用于构建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安装最新版本

运行特定测试

  1. nox -e test仅运行单元测试;
  2. nox -e lint运行所有linters和formatter;
  3. nox -e codeqa运行flake8pylintreuse lintantsibull-changelog lint
  4. nox -e formatters运行isortblack
  5. 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.csssphinx_antsibull_ext/css/antsibull-minimal.scss 使用 SASSpostcss,并通过 autoprefixercssnano 构建。

使用位于 sphinx_antsibull_ext/css/ 下的脚本 build.sh.scss 文件构建 .css 文件。

cd sphinx_antsibull_ext/css/
./build-css.sh

为此,您需要安装一些Node.js依赖项。

npm clean-install

创建新版本

  1. 运行 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
  2. 运行 git push 到相应的远程仓库。
  3. 一旦GitHub上的CI通过,运行 nox -e publish。这将
    • 运行 hatch publish
    • 将版本提升到 <version>.post0
    • 将更改的文件添加到git并运行 git commit -m 'Post-release version bump.'
  4. git push --follow-tags 运行到相应的远程仓库并创建GitHub版本。

许可证

除非代码中有其他说明,否则它遵循GNU通用公共许可证v3的条款,或者根据您的选择,使用更晚的版本。有关许可证副本,请参阅 LICENSES/GPL-3.0-or-later.txt

该仓库遵循 REUSE规范 以声明版权和许可信息。唯一的例外是位于 changelog/fragments/ 的更改日志片段。

项目详细信息


下载文件

下载适合您平台的文件。如果您不确定选择哪个,请了解更多关于 安装包 的信息。

源分发

antsibull_docs-2.14.0.tar.gz (1.4 MB 查看哈希值)

构建分发

antsibull_docs-2.14.0-py3-none-any.whl (271.8 kB 查看哈希值)

上传时间 Python 3

由以下支持