From 80ba7b74022578e0685ea030e88821e87f28c520 Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Mon, 12 Mar 2018 21:50:52 +0100 Subject: [PATCH] Various module doc fixes (#37256) This PR includes: - A fix for multiple-choice defaults - A fix for messed up dictionary samples - Cleaner defaults when they don't appear part of choices --- docs/templates/plugin.rst.j2 | 38 +++---- .../modules/storage/zfs/zpool_facts.py | 100 ++++++++++-------- lib/ansible/modules/windows/win_acl.py | 4 +- 3 files changed, 74 insertions(+), 68 deletions(-) diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2 index 66a7b717fdd..84bc5a4f66c 100644 --- a/docs/templates/plugin.rst.j2 +++ b/docs/templates/plugin.rst.j2 @@ -107,6 +107,7 @@ Parameters {# default / choices #}
+ {# Recalculate choices and boolean values #} {% if value.default is defined %} {% if value.default == true %} {% set _x = value.update({'default': 'yes'}) %} @@ -117,21 +118,21 @@ Parameters {% if value.type == 'bool' %} {% set _x = value.update({'choices': ['no', 'yes']}) %} {% endif %} + {# Show possible choices and highlight details #} {% if value.choices %} -
@@ -239,8 +240,7 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a
{% for i in range(1, loop.depth) %} -
-
+
{% endfor %}
@{ key }@ @@ -248,7 +248,7 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a
-
@{ value.returned }@
+
@{ value.returned | html_ify }@
{% if value.description is string %} @@ -259,10 +259,10 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a {% endfor %} {% endif %}
- {% if value.sample %} + {% if value.sample is defined and value.sample %}
Sample:
-{#
@{ value.sample | html_ify }@
#} -
@{ value.sample | html_ify }@
+ {# TODO: The sample should be escaped, using | escape or | htmlify, but both mess things up beyond repair with dicts #} +
@{ value.sample | replace('\n', '\n ') | html_ify }@
{% endif %}
@@ -313,7 +313,7 @@ Common return values are documented :ref:`here `, the foll -
@{ value.returned }@
+
@{ value.returned | html_ify }@
{% if value.description is string %} @@ -324,10 +324,10 @@ Common return values are documented :ref:`here `, the foll {% endfor %} {% endif %}
- {% if value.sample %} + {% if value.sample is defined and value.sample %}
Sample:
-{#
@{ value.sample | html_ify }@
#} -
@{ value.sample | html_ify }@
+ {# TODO: The sample should be escaped, using | escape or | htmlify, but both mess things up beyond repair with dicts #} +
@{ value.sample | replace('\n', '\n ') | html_ify }@
{% endif %}
diff --git a/lib/ansible/modules/storage/zfs/zpool_facts.py b/lib/ansible/modules/storage/zfs/zpool_facts.py index 3063d24e7d2..5fdc9b74e6d 100644 --- a/lib/ansible/modules/storage/zfs/zpool_facts.py +++ b/lib/ansible/modules/storage/zfs/zpool_facts.py @@ -49,11 +49,63 @@ EXAMPLES = ''' # Gather space usage about all imported ZFS pools - zpool_facts: properties='free,size' - debug: msg='ZFS pool {{ item.name }} has {{ item.free }} free space out of {{ item.size }}.' + +- debug: msg='ZFS pool {{ item.name }} has {{ item.free }} free space out of {{ item.size }}.' with_items: '{{ ansible_zfs_pools }}' ''' RETURN = ''' +ansible_facts: + description: Dictionary containing all the detailed information about the ZFS pool facts + returned: always + type: complex + contains: + ansible_zfs_pools: + description: ZFS pool facts + returned: always + type: string + sample: + { + "allocated": "3.46G", + "altroot": "-", + "autoexpand": "off", + "autoreplace": "off", + "bootfs": "rpool/ROOT/openindiana", + "cachefile": "-", + "capacity": "6%", + "comment": "-", + "dedupditto": "0", + "dedupratio": "1.00x", + "delegation": "on", + "expandsize": "-", + "failmode": "wait", + "feature@async_destroy": "enabled", + "feature@bookmarks": "enabled", + "feature@edonr": "enabled", + "feature@embedded_data": "active", + "feature@empty_bpobj": "active", + "feature@enabled_txg": "active", + "feature@extensible_dataset": "enabled", + "feature@filesystem_limits": "enabled", + "feature@hole_birth": "active", + "feature@large_blocks": "enabled", + "feature@lz4_compress": "active", + "feature@multi_vdev_crash_dump": "enabled", + "feature@sha512": "enabled", + "feature@skein": "enabled", + "feature@spacemap_histogram": "active", + "fragmentation": "3%", + "free": "46.3G", + "freeing": "0", + "guid": "15729052870819522408", + "health": "ONLINE", + "leaked": "0", + "listsnapshots": "off", + "name": "rpool", + "readonly": "off", + "size": "49.8G", + "version": "-" + } name: description: ZFS pool name returned: always @@ -64,52 +116,6 @@ parsable: returned: if 'parsable' is set to True type: boolean sample: True -zfs_pools: - description: ZFS pool facts - returned: always - type: string - sample: - { - "allocated": "3.46G", - "altroot": "-", - "autoexpand": "off", - "autoreplace": "off", - "bootfs": "rpool/ROOT/openindiana", - "cachefile": "-", - "capacity": "6%", - "comment": "-", - "dedupditto": "0", - "dedupratio": "1.00x", - "delegation": "on", - "expandsize": "-", - "failmode": "wait", - "feature@async_destroy": "enabled", - "feature@bookmarks": "enabled", - "feature@edonr": "enabled", - "feature@embedded_data": "active", - "feature@empty_bpobj": "active", - "feature@enabled_txg": "active", - "feature@extensible_dataset": "enabled", - "feature@filesystem_limits": "enabled", - "feature@hole_birth": "active", - "feature@large_blocks": "enabled", - "feature@lz4_compress": "active", - "feature@multi_vdev_crash_dump": "enabled", - "feature@sha512": "enabled", - "feature@skein": "enabled", - "feature@spacemap_histogram": "active", - "fragmentation": "3%", - "free": "46.3G", - "freeing": "0", - "guid": "15729052870819522408", - "health": "ONLINE", - "leaked": "0", - "listsnapshots": "off", - "name": "rpool", - "readonly": "off", - "size": "49.8G", - "version": "-" - } ''' from collections import defaultdict diff --git a/lib/ansible/modules/windows/win_acl.py b/lib/ansible/modules/windows/win_acl.py index ec6dc53ffbd..c0655b054f1 100644 --- a/lib/ansible/modules/windows/win_acl.py +++ b/lib/ansible/modules/windows/win_acl.py @@ -56,8 +56,8 @@ options: C(ObjectInherit). - For more information on the choices see MSDN InheritanceFlags enumeration at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx). - choices: [ ContainerInherit, None, ObjectInherit ] - default: For Leaf File, 'None'; For Directory, 'ContainerInherit, ObjectInherit'; + - Defaults to C(ContainerInherit, ObjectInherit) for Directories. + choices: [ ContainerInherit, ObjectInherit ] propagation: description: - Propagation flag on the ACL rules.