Ansible - сгенерировать .rst файл из строки ДОКУМЕНТАЦИИ модуля
Я написал собственный модуль 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?
Ответы 1
Используя предоставленный Makefile в каталоге docs/docsite (вы также можете запустить make webdocs с верхнего уровня). Убедитесь, что вы загрузили требования к документации в свой virtualenv в дополнение к pip install -e $PWD или его эквиваленту, потому что docsite sphinx использует некоторые из собственных библиотек ansible для выполнения своей работы.
@mdaniel, вы можете сказать мне, куда нужно скопировать специальный модуль (файл .py), чтобы сгенерировать первый файл? Я попытался скопировать mymodule.py (файл моего настраиваемого модуля) в lib / ansible / modules / $ CATEGORY /, как указано в docs.ansible.com/ansible/2.5/dev_guide/…, но я не уверен, правильно ли я делаю это, не могли бы вы помочь мне здесь ?
Да вроде работает. Я обнаружил, что напрямую использовать скрипт форматирования плагинов, например
cd /data/github/ansible/docs/, а затемbin/plugin_formatter.py -t rst --template-dir=templates -o rst --module-dir=${custom_module_path}, проще. К сожалению, похоже, что Шаблоны Ansible по умолчанию использует довольно много встроенного HTML, что выглядит не очень хорошо, когда я пытаюсь использовать его со стандартными темами Sphinx (такими как Alabaster). В общем, это немного хакерское решение - похоже, нет правильного способа сделать это за пределами Anisble.