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

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字符串不同。

尽管Ansible module documentation进行了深入介绍，但应如何设置文档字符串的格式，但这似乎并未提供任何有关如何在本地生成文档的信息。

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

Answer 1

通过使用docs/docsite目录中的release notes（也可以从顶层运行the provided Makefile）。您将要确保除了pip install -e $PWD或其等效项之外，还已经将make webdocs加载到您的virtualenv中，因为docsite sphinx使用ansible自己的一些库来完成其工作。