构建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 |