Ansible - сгенерировать .rst файл из строки DOCUMENTATION модуля

Question

Я написал собственный модуль Ansible и задокументировал его, используя стандартное соглашение Ansible, т.е. , записав DOCUMENTATION и EXAMPLES глобальные строки в файле модуля.

У меня уже есть некоторые издокументация, созданная с использованием Sphinx 1.8.3 и размещенная локально.Я хотел бы, чтобы документация Ansible была включена в сгенерированные Sphinx страницы.Моя структура каталогов довольно проста:

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

Теперь я могу написать документацию в виде строки документации функции, а затем включить ее, используя директиву Sphinx .. automodule::.Это работает, но использует формат, отличный от строки Ansible DOCUMENTATION.

Хотя Документация по модулю Ansible подробно описывается, как следует форматировать строки документации, похоже, что она не предоставляет никакой информациикак создавать документы локально.

Как правильно преобразовать документацию модуля Ansible в файл .rst, чтобы он мог быть включен в Sphinx?

Answer 1

Используя предоставленный Makefile в каталоге docs/docsite (вы также можете запустить make webdocs с верхнего уровня).Вам нужно убедиться, что вы загрузили требования к документу в ваш virtualenv, в дополнение к pip install -e $PWD или его эквиваленту, потому что сфинкс документа использует некоторые из собственных библиотек ansible для своей работы.