Ansible

Question

我编写了自定义 Ansible 模块并使用标准 Ansible 约定对其进行了记录，即通过在模块文件中写入 DOCUMENTATION 和 EXAMPLES 全局字符串。

我已经有了一些使用 Sphinx 1.8.3 生成并在本地托管的文档。我想在 Sphinx 生成的页面中包含 Ansible 文档。我的目录结构相当简单：

./ansible/docs
├── conf.py
├── index.rst
├── _static
└── _templates
./ansible/library/
├── __init__.py
└── module.py

现在，我可以将文档编写为函数文档字符串，然后使用 Sphinx .. automodule:: 指令将其包含在内。这有效，但使用与 Ansible DOCUMENTATION string.

不同的格式

虽然Ansible module documentation深入探讨了文档字符串应该如何格式化，但它似乎没有提供任何关于如何在本地生成文档的信息。

将 Ansible 模块文档转换为 .rst 文件的正确方法是什么，以便它可以被 Sphinx 包含？

Answer 1

通过在你的 virtualenv 中使用 the provided Makefile in the docs/docsite directory (you can also run make webdocs from the top-level). You'll want to ensure you have loaded the docsite requirements，除了 pip install -e $PWD 或其等价物，因为 docsite sphinx 使用一些 ansible 自己的库来完成它的工作。

Ansible - 从模块的 DOCUMENTATION 字符串生成 .rst 文件

Ansible - generate .rst file from module's DOCUMENTATION string

python

documentation

restructuredtext

python-sphinx