使用模板从带注释的行动手册和角色生成文档
ansible-autodoc的Python项目详细描述
ansible autodoc
使用模板从带注释的行动手册和角色生成文档。
Note: this project is currently in Beta, issues, ideas and pull requests are welcome.
功能
- 允许记录行动手册项目和角色
- 使用模板生成和维护文档
- 记录时的扩展功能：
- 标记：autodoc将在项目中搜索使用过的标记
入门
# install
pip install ansible-autodoc
# print help
ansible-autodoc -h
# print parsed annotation results in the cli
ansible-autodoc -p all path/to/role_or_playbook
# generate README file based on annotations
ansible-autodoc [path/to/project]
注意：
- 您可以使用grip查看实时更改。
- 这只适用于python 3，如果还有python 2.x，请使用pip3
注释
在行动手册和角色中使用以下注释
- meta:使用@meta注释playbook或role的元数据，如author
检查以下有用元数据列表
- 作者：（不言自明）
- 描述：剧本/角色描述
- 名称：定义不同的角色/项目名称而不是文件夹名称
- 许可证：（不言自明）
- 电子邮件：（不言自明）
# @meta author: Author Name# @meta description: Project description
- todo:使用@todo注释改进、错误等
# @todo bug: bug description# @todo improvement: improvement
- action:使用@action注释剧本/角色执行的操作
# @action install # this action describes the installation # @action # this action does not have a section, only description
- 标记：使用@tag来注释标记，这是一个特殊的注释，因为这不仅会搜索注释， 但也用于项目中使用的标记，并将其添加到生成的输出中。
# @tag tagname # tag description - 变量：使用@var this注释配置变量
# @var my_var: default_value # description of the variable - example:想法是，在每个注释之后，我们可以定义一个链接到注释的示例块。 在这种情况下，示例将是var注释的一部分。
# @var my_var: default_value # description of the variable my_var:default_value# @example # the hash is needed due to the parser constrains# my_var:# - subitem: string# - subitem2: string# @end
模板
Ansible Autodoc提供了3个现成的模板，默认为“自述文件”，您可以在配置中更改它。
如果要创建自己的特定于项目的模板，请参见template documentation
如果输出中已经存在一个文件，则会提示您重写或中止。
自述文件
默认的“readme”模板将在项目的根目录中生成一个readme.md文件，详细说明以下部分：
- 标题和说明
- 操作
- 标签
- 变量
- 待办事项
- 许可证
- 作者信息
您可以在项目的根目录中扩展我的创建文件"_readme_doby.md"，它将在
初始描述。
文档和自述文件
“doc_and_readme”模板是一个扩展模板，用于具有多个角色的playbook项目，它将生成最小的 readme.md文件和包含更多详细信息的文档子文件夹“doc”。
您可以在项目的根目录中扩展我的创建文件"_readme_doby.md"，它将在
初始描述。
在文档文件夹中创建的文件将包括：
- 标记：列出按角色分类的所有标记
- 变量：列出按角色分类的所有变量
- TOdo:列出按角色分类的所有TOdo操作
- 报告：提供项目报告和开发过程中的有用信息
您可以扩展此文件夹中的文档，只需记住生成的文件将被覆盖。
命令行
“cliprint”模板用于在使用命令行打印参数“-p”
配置
您可以在项目的根目录中创建配置文件“autodoc.config.yaml”，以便修改 一些行为，请参见示例配置文件以了解更多详细信息：
# role or project with playbooks $ cd <project> # create sample configuration (optional) # you can pass the options as parameters too $ ansible-autodoc --sample-doc > autodoc.config.yaml
欢迎加入QQ群-->： 979659372
