aar-doc - 自动化Ansible角色文档

aar-doc 是一个从Ansible角色元数据自动生成文档的工具。具体来说，它读取 meta/main.yml 和 meta/argument_specs.yml 文件。

它深受 terraform-docs 的启发，后者与Terraform模块执行类似操作。不过，aar-doc 的功能远不如它丰富，但应该能解决问题！

例如，支持的唯一输出格式是Markdown。与 terraform-docs 一样，您可以覆盖默认模板。由于Ansible用户熟悉 Jinja2，因此 aar-doc 使用它进行模板化。

欢迎贡献以添加对更多输出格式的支持！

安装

由于 aar-doc 是一个Python实用工具，并且存在于 PyPI 上 （链接），因此可以使用常规的 pip install 命令。

pip install aar-doc

用法

 Usage: aar-doc [OPTIONS] ROLE_PATH COMMAND [ARGS]...

 A tool for generating docs for Ansible roles.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    role_path      DIRECTORY  Path to an Ansible role [default: None]       │
│                                [required]                                    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --config-file               FILE              [default: .aar_doc.yml]        │
│ --output-file               FILE              [default: README.md]           │
│ --output-template           TEXT              Output template as a string or │
│                                               a path to a file.              │
│                                               [default: <!--                 │
│                                               BEGIN_ANSIBLE_DOCS -->         │
│                                               {{ content }}                  │
│                                               <!-- END_ANSIBLE_DOCS -->      │
│                                               ]                              │
│ --output-mode               [inject|replace]  [default: inject]              │
│ --install-completion                          Install completion for the     │
│                                               current shell.                 │
│ --show-completion                             Show completion for the        │
│                                               current shell, to copy it or   │
│                                               customize the installation.    │
│ --help                                        Show this message and exit.    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ markdown   Command for generating role documentation in Markdown format.     │
╰──────────────────────────────────────────────────────────────────────────────╯

模式

inject 模式只会在 BEGIN_ANSIBLE_DOCS 和 END_ANSIBLE_DOCS 标记之间注入更改的内容。这使得可以在文件中包含不更改的页眉和页脚文本。这是默认模式，如果文件不存在，将回退到 replace 以在第一次创建文件时创建它。

“替换”模式会将整个文件替换为模板。通常情况下，“注入”模式适用于常规使用，除非您想覆盖现有文件，否则不需要更改模式。

配置

配置选项可以通过--help中显示的CLI参数提供，或者通过YAML格式的--config-file提供。请注意，通过配置文件提供的选项带有下划线。

示例

aar-doc --output-file ROLE.md --output-mode replace ...

---
output_file: ROLE.md
output_mode: replace

模板化

您可以覆盖用于渲染文档的--output-template。这可能是一个包含Jinja2的字符串或文件的路径。如上所述，此选项可以通过CLI或配置文件传递。

在配置文件中，最简单的是使用多行字符串

---
output_template: |
  <!-- BEGIN_ANSIBLE_DOCS -->

  This is my role: {{ role }}

  <!-- END_ANSIBLE_DOCS -->

如上所述，模板必须以注释形式开始和结束，以便内容注入正常工作。

{{ content }}将包含由内置模板渲染的特定模板内容。对于Markdown，请参阅templates/markdown.j2。

但是，您很可能希望在自己的模板中跳过使用它，并直接使用包含角色元数据和参数规范的变量。aar-doc不会以任何方式操纵来自YAML文件中的值。

模板变量

• role：角色名称
• content：内置模板预渲染的整个内容
• metadata：从meta/main.yml读取的元数据
• argument_specs：从meta/argument_specs.yml读取的元数据

示例

<!-- BEGIN_ANSIBLE_DOCS -->

This is my role: {{ role }}

<!-- 'metadata' contains all the things in meta/main.yml -->
{{ metadata.galaxy_info.license }}

<!-- All the usual Jinja2 filters are available -->
{{ metadata.galaxy_info.galaxy_tags | sort }}

<!-- Including files is also possible in relation to the role's directory with Jinja2's include directive -->
{% include "defaults/main.yml" %}

<!-- 'argument_specs' contains all the things in meta/argument_specs.yml -->
{% for entrypoint, specs in argument_specs | items %}
Task file name: {{ entrypoint }}.yml has {{ specs | length }} input variables!
{% endfor %}
<!-- END_ANSIBLE_DOCS -->

aar-doc --output-template ./path/to/template.j2 ...

更多示例可以在tests中找到。

许可证

MIT

致谢

• 向原始作者Miika Kankare表示敬意！
• 向Kevin P. Fleming表示敬意，他为原始项目做出了贡献！