Документирование вашего модуля

• Авторские права
• Блок ANSIBLE_METADATA
  • Версия 1.1 метаданных
    • Структура
    • Поля
  • Изменения с версии 1.0
• Блок DOCUMENTATION
• Блок EXAMPLES
• Блок RETURN
• Импорты Python
• Параметры форматирования
• Фрагменты документации
• Тестирование документации

Онлайн-документация модуля генерируется из самих модулей. Поскольку документация модуля генерируется из строк документации, содержащихся в модулях, все модули, включенные в Ansible, должны содержать строку DOCUMENTATION. Эта строка должна быть допустимым документом YAML, который соответствует схеме, определенной ниже. Вам может быть проще начать написание строки DOCUMENTATION в редакторе с подсветкой синтаксиса YAML, прежде чем включить её в ваш файл Python.

Все модули должны иметь следующие разделы в указанном порядке:

1. Авторские права
2. ANSIBLE_METADATA
3. DOCUMENTATION
4. EXAMPLES
5. RETURN
6. Импорты Python

Авторские права

Начало каждого модуля должно быть примерно одинаковым. После shebang должно быть как минимум две строки, охватывающие авторские права и лицензию на код.

#!/usr/bin/python
# Copyright (c) 2017 Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

Каждый файл должен иметь строку авторских прав с исходным правообладателем. Значительные дополнения к модулю (например, переписывания) могут добавить дополнительные строки авторских прав. Код из сообщества Ansible обычно присваивается как «Copyright (c) 2017 Ansible Project», что охватывает всех авторов. Любые юридические вопросы необходимо просмотреть в истории контроля версий, поэтому исчерпывающий заголовок авторских прав не требуется.

Заявление о лицензии должно быть ТОЛЬКО одной строкой, а не полным префиксом GPL. Если вы заметите модуль с полным префиксом, вы можете заменить его на однострочное объявление.

При добавлении строки авторских прав после завершения значительной функции или переписывания добавьте новую строку выше старой, как показано ниже:

#!/usr/bin/python
# Copyright (c) 2017 [New Contributor(s)]
# Copyright (c) 2015 [Original Contributor(s)]
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

Блок ANSIBLE_METADATA

ANSIBLE_METADATA содержит информацию о модуле для использования другими инструментами. В настоящее время он информирует другие инструменты о типе основного разработчика модуля и о степени, в которой пользователи могут полагаться на неизменность поведения модуля с течением времени.

Для новых модулей следующий блок можно просто добавить в ваш модуль

ANSIBLE_METADATA = {'metadata_version': '1.1',
                    'status': ['preview'],
                    'supported_by': 'community'}

Версия 1.1 метаданных

Структура

ANSIBLE_METADATA = {
    'metadata_version': '1.1',
    'supported_by': 'community',
    'status': ['preview', 'deprecated']
}

Поля

Изменения с версии 1.0

Блок DOCUMENTATION

Пример строки документации см. в репозитории по адресу examples/DOCUMENTATION.yml.

Включите его в свой файл модуля так:

#!/usr/bin/python
# Copyright (c) 2017 [REPLACE THIS]
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

DOCUMENTATION = '''
---
module: modulename
short_description: This is a sentence describing the module
# ... snip ...
'''

Следующие поля могут быть использованы и являются обязательными, если не указано иное:

Блок ПРИМЕРЫ

Раздел ПРИМЕРЫ требуется для всех новых модулей.

Примеры должны демонстрировать реальное использование и быть написаны в формате YAML с несколькими строками.

Убедитесь, что примеры синхронизированы с опциями во время проверки PR и любых последующих рефакторингов кода.

В соответствии с лучшими практиками для playbook, должен быть указан name:.

EXAMPLES строка внутри модуля так:

EXAMPLES = '''
- name: Ensure foo is installed
  modulename:
    name: foo
    state: present
'''

Если модуль возвращает факты, которые часто нужны, пример того, как их использовать, может быть полезен.

Блок ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ

Раздел ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ документирует, что возвращает модуль, и он требуется для всех новых модулей.

Для каждого возвращаемого значения укажите description, в каких обстоятельствах возвращается это значение returned, type значения и sample. Например, из модуля copy:

Следующие поля могут быть использованы и являются обязательными, если не указано иное.

Для сложных вложенных возвратов тип может быть указан как type: complex.

Пример:

RETURN = '''
dest:
    description: destination file/path
    returned: success
    type: string
    sample: /path/to/file.txt
src:
    description: source file used for the copy on the target machine
    returned: changed
    type: string
    sample: /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source
md5sum:
    description: md5 checksum of the file after running copy
    returned: when supported
    type: string
    sample: 2a5aeecc61dc98c4d780b14b330e3282
...

Импорты Python

Начиная с версии Ansible 2.2, все новые модули должны использовать импорты в виде:

from module_utils.basic import AnsibleModule

Параметры форматирования

Эти функции форматирования предназначены для U() для URL-адресов, I() для имён опций, C() для файлов и значений опций и M() для имён модулей. Имена модулей должны быть указаны как M(module) для создания ссылки на онлайн-документацию по этому модулю.

Пример использования:

Or if not set the environment variable C(ACME_PASSWORD) will be used.
...
Required if I(state=present)
...
Mutually exclusive with I(project_src) and I(files).
...
See also M(win_copy) or M(win_template).
...
See U(https://www.ansible.com/tower) for an overview.

Фрагменты документации

Некоторые категории модулей имеют общую документацию, например, подробности об параметрах аутентификации или параметрах режима файла. Вместо дублирования этой информации, её можно использовать в docs_fragments.

Эти общие фрагменты похожи на стандартный блок документации, используемый в модуле, но содержатся в ModuleDocFragment классе.

Все существующие docs_fragments находятся в lib/ansible/utils/module_docs_fragments/.

Для включения просто добавьте extends_documentation_fragment: FRAGMENT_NAME в ваш модуль.

Примеры можно найти, выполнив поиск по extends_documentation_fragment в дереве исходного кода Ansible.

Тестирование документации

Поместите ваш завершённый модульный файл в директорию lib/ansible/modules/$CATEGORY/ и затем выполните команду: make webdocs. Новый файл ‘modules.html’ будет создан в директории docs/docsite/_build/html/$MODULENAME_module.html.

Для ускорения процесса сборки, вы можете ограничить создание документации только указанными модулями или вообще без модулей. Для этого выполните команду: MODULES=$MODULENAME make webdocs. Переменная среды MODULES принимает список имён модулей, разделённых запятыми. Чтобы пропустить создание документации для всех модулей, укажите несуществующее имя модуля, например: MODULES=none make webdocs.

Вы также можете создать отдельную страницу всего сайта документации. Из ansible/docs/docsite выполните make htmlsingle rst=[relative path to the .rst file], например: make htmlsingle rst=dev_guide/developing_modules_documenting.rst

Для тестирования вашей документации относительно вашего argument_spec вы можете использовать validate-modules. Обратите внимание, что этот вариант в настоящее время не включён в Shippable из-за времени, необходимого для его выполнения.

# If you don't already, ensure you are using your local checkout
source hacking/env-setup
./test/sanity/validate-modules/validate-modules --arg-spec --warnings  lib/ansible/modules/your/modules/

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