Browse code
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
(cherry picked from commit 80ba7b74022578e0685ea030e88821e87f28c520)
Dag Wieers authored on 2018/03/13 05:50:52Showing 3 changed files
- docs/templates/plugin.rst.j2
- lib/ansible/modules/storage/zfs/zpool_facts.py
- lib/ansible/modules/windows/win_acl.py
| ... | ... |
@@ -107,6 +107,7 @@ Parameters |
| 107 | 107 |
{# default / choices #}
|
| 108 | 108 |
<td> |
| 109 | 109 |
<div class="cell-border"> |
| 110 |
+ {# Recalculate choices and boolean values #}
|
|
| 110 | 111 |
{% if value.default is defined %}
|
| 111 | 112 |
{% if value.default == true %}
|
| 112 | 113 |
{% set _x = value.update({'default': 'yes'}) %}
|
| ... | ... |
@@ -117,21 +118,21 @@ Parameters |
| 117 | 117 |
{% if value.type == 'bool' %}
|
| 118 | 118 |
{% set _x = value.update({'choices': ['no', 'yes']}) %}
|
| 119 | 119 |
{% endif %}
|
| 120 |
+ {# Show possible choices and highlight details #}
|
|
| 120 | 121 |
{% if value.choices %}
|
| 121 |
- <ul style="list-style-type: circle"><b>Choices:</b> |
|
| 122 |
- {% if value.default not in value.choices %}
|
|
| 123 |
- <li type="disc"><div style="color: blue"><b>@{ value.default }@</b> ←</div></li>
|
|
| 124 |
- {% endif %}
|
|
| 122 |
+ <ul><b>Choices:</b> |
|
| 125 | 123 |
{% for choice in value.choices %}
|
| 126 |
- {% if value.default is defined and choice == value.default %}
|
|
| 127 |
- <li type="disc"><div style="color: blue"><b>@{ value.default }@</b> ←</div></li>
|
|
| 124 |
+ {% if (value.default is string and choice == value.default) or (value.default is iterable and choice in value.default) %}
|
|
| 125 |
+ <li type="disc"><div style="color: blue"><b>@{ choice | escape }@</b> ←</div></li>
|
|
| 128 | 126 |
{% else %}
|
| 129 |
- <li>@{ choice }@</li>
|
|
| 127 |
+ <li type="circle">@{ choice | escape }@</li>
|
|
| 130 | 128 |
{% endif %}
|
| 131 | 129 |
{% endfor %}
|
| 132 | 130 |
</ul> |
| 133 |
- {% elif value.default is defined %}
|
|
| 134 |
- <div style="color: blue">@{ value.default | html_ify }@</div>
|
|
| 131 |
+ {% endif %}
|
|
| 132 |
+ {# Show default value, when multiple choice or no choices #}
|
|
| 133 |
+ {% if value.default is defined and value.default not in value.choices %}
|
|
| 134 |
+ <b>Default:</b><br/><div style="color: blue">@{ value.default | escape }@</div>
|
|
| 135 | 135 |
{% endif %}
|
| 136 | 136 |
</div> |
| 137 | 137 |
</td> |
| ... | ... |
@@ -239,8 +240,7 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a |
| 239 | 239 |
<td> |
| 240 | 240 |
<div class="outer-elbow-container"> |
| 241 | 241 |
{% for i in range(1, loop.depth) %}
|
| 242 |
- <div class="elbow-placeholder"> |
|
| 243 |
- </div> |
|
| 242 |
+ <div class="elbow-placeholder"></div> |
|
| 244 | 243 |
{% endfor %}
|
| 245 | 244 |
<div class="elbow-key"> |
| 246 | 245 |
<b>@{ key }@</b>
|
| ... | ... |
@@ -248,7 +248,7 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a |
| 248 | 248 |
</div> |
| 249 | 249 |
</div> |
| 250 | 250 |
</td> |
| 251 |
- <td><div class="cell-border">@{ value.returned }@</div></td>
|
|
| 251 |
+ <td><div class="cell-border">@{ value.returned | html_ify }@</div></td>
|
|
| 252 | 252 |
<td> |
| 253 | 253 |
<div class="cell-border"> |
| 254 | 254 |
{% if value.description is string %}
|
| ... | ... |
@@ -259,10 +259,10 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a |
| 259 | 259 |
{% endfor %}
|
| 260 | 260 |
{% endif %}
|
| 261 | 261 |
<br/> |
| 262 |
- {% if value.sample %}
|
|
| 262 |
+ {% if value.sample is defined and value.sample %}
|
|
| 263 | 263 |
<div style="font-size: smaller"><b>Sample:</b></div> |
| 264 |
-{# <div style="font-size: smaller; color: blue; word-wrap: break-word; overflow-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> #}
|
|
| 265 |
- <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div>
|
|
| 264 |
+ {# TODO: The sample should be escaped, using | escape or | htmlify, but both mess things up beyond repair with dicts #}
|
|
| 265 |
+ <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | replace('\n', '\n ') | html_ify }@</div>
|
|
| 266 | 266 |
{% endif %}
|
| 267 | 267 |
</div> |
| 268 | 268 |
</td> |
| ... | ... |
@@ -313,7 +313,7 @@ Common return values are documented :ref:`here <common_return_values>`, the foll |
| 313 | 313 |
</div> |
| 314 | 314 |
</div> |
| 315 | 315 |
</td> |
| 316 |
- <td><div class="cell-border">@{ value.returned }@</div></td>
|
|
| 316 |
+ <td><div class="cell-border">@{ value.returned | html_ify }@</div></td>
|
|
| 317 | 317 |
<td> |
| 318 | 318 |
<div class="cell-border"> |
| 319 | 319 |
{% if value.description is string %}
|
| ... | ... |
@@ -324,10 +324,10 @@ Common return values are documented :ref:`here <common_return_values>`, the foll |
| 324 | 324 |
{% endfor %}
|
| 325 | 325 |
{% endif %}
|
| 326 | 326 |
<br/> |
| 327 |
- {% if value.sample %}
|
|
| 327 |
+ {% if value.sample is defined and value.sample %}
|
|
| 328 | 328 |
<div style="font-size: smaller"><b>Sample:</b></div> |
| 329 |
-{# <div style="font-size: smaller; color: blue; word-wrap: break-word; overflow-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> #}
|
|
| 330 |
- <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div>
|
|
| 329 |
+ {# TODO: The sample should be escaped, using | escape or | htmlify, but both mess things up beyond repair with dicts #}
|
|
| 330 |
+ <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | replace('\n', '\n ') | html_ify }@</div>
|
|
| 331 | 331 |
{% endif %}
|
| 332 | 332 |
</div> |
| 333 | 333 |
</td> |
| ... | ... |
@@ -49,11 +49,63 @@ EXAMPLES = ''' |
| 49 | 49 |
|
| 50 | 50 |
# Gather space usage about all imported ZFS pools |
| 51 | 51 |
- zpool_facts: properties='free,size' |
| 52 |
- debug: msg='ZFS pool {{ item.name }} has {{ item.free }} free space out of {{ item.size }}.'
|
|
| 52 |
+ |
|
| 53 |
+- debug: msg='ZFS pool {{ item.name }} has {{ item.free }} free space out of {{ item.size }}.'
|
|
| 53 | 54 |
with_items: '{{ ansible_zfs_pools }}'
|
| 54 | 55 |
''' |
| 55 | 56 |
|
| 56 | 57 |
RETURN = ''' |
| 58 |
+ansible_facts: |
|
| 59 |
+ description: Dictionary containing all the detailed information about the ZFS pool facts |
|
| 60 |
+ returned: always |
|
| 61 |
+ type: complex |
|
| 62 |
+ contains: |
|
| 63 |
+ ansible_zfs_pools: |
|
| 64 |
+ description: ZFS pool facts |
|
| 65 |
+ returned: always |
|
| 66 |
+ type: string |
|
| 67 |
+ sample: |
|
| 68 |
+ {
|
|
| 69 |
+ "allocated": "3.46G", |
|
| 70 |
+ "altroot": "-", |
|
| 71 |
+ "autoexpand": "off", |
|
| 72 |
+ "autoreplace": "off", |
|
| 73 |
+ "bootfs": "rpool/ROOT/openindiana", |
|
| 74 |
+ "cachefile": "-", |
|
| 75 |
+ "capacity": "6%", |
|
| 76 |
+ "comment": "-", |
|
| 77 |
+ "dedupditto": "0", |
|
| 78 |
+ "dedupratio": "1.00x", |
|
| 79 |
+ "delegation": "on", |
|
| 80 |
+ "expandsize": "-", |
|
| 81 |
+ "failmode": "wait", |
|
| 82 |
+ "feature@async_destroy": "enabled", |
|
| 83 |
+ "feature@bookmarks": "enabled", |
|
| 84 |
+ "feature@edonr": "enabled", |
|
| 85 |
+ "feature@embedded_data": "active", |
|
| 86 |
+ "feature@empty_bpobj": "active", |
|
| 87 |
+ "feature@enabled_txg": "active", |
|
| 88 |
+ "feature@extensible_dataset": "enabled", |
|
| 89 |
+ "feature@filesystem_limits": "enabled", |
|
| 90 |
+ "feature@hole_birth": "active", |
|
| 91 |
+ "feature@large_blocks": "enabled", |
|
| 92 |
+ "feature@lz4_compress": "active", |
|
| 93 |
+ "feature@multi_vdev_crash_dump": "enabled", |
|
| 94 |
+ "feature@sha512": "enabled", |
|
| 95 |
+ "feature@skein": "enabled", |
|
| 96 |
+ "feature@spacemap_histogram": "active", |
|
| 97 |
+ "fragmentation": "3%", |
|
| 98 |
+ "free": "46.3G", |
|
| 99 |
+ "freeing": "0", |
|
| 100 |
+ "guid": "15729052870819522408", |
|
| 101 |
+ "health": "ONLINE", |
|
| 102 |
+ "leaked": "0", |
|
| 103 |
+ "listsnapshots": "off", |
|
| 104 |
+ "name": "rpool", |
|
| 105 |
+ "readonly": "off", |
|
| 106 |
+ "size": "49.8G", |
|
| 107 |
+ "version": "-" |
|
| 108 |
+ } |
|
| 57 | 109 |
name: |
| 58 | 110 |
description: ZFS pool name |
| 59 | 111 |
returned: always |
| ... | ... |
@@ -64,52 +116,6 @@ parsable: |
| 64 | 64 |
returned: if 'parsable' is set to True |
| 65 | 65 |
type: boolean |
| 66 | 66 |
sample: True |
| 67 |
-zfs_pools: |
|
| 68 |
- description: ZFS pool facts |
|
| 69 |
- returned: always |
|
| 70 |
- type: string |
|
| 71 |
- sample: |
|
| 72 |
- {
|
|
| 73 |
- "allocated": "3.46G", |
|
| 74 |
- "altroot": "-", |
|
| 75 |
- "autoexpand": "off", |
|
| 76 |
- "autoreplace": "off", |
|
| 77 |
- "bootfs": "rpool/ROOT/openindiana", |
|
| 78 |
- "cachefile": "-", |
|
| 79 |
- "capacity": "6%", |
|
| 80 |
- "comment": "-", |
|
| 81 |
- "dedupditto": "0", |
|
| 82 |
- "dedupratio": "1.00x", |
|
| 83 |
- "delegation": "on", |
|
| 84 |
- "expandsize": "-", |
|
| 85 |
- "failmode": "wait", |
|
| 86 |
- "feature@async_destroy": "enabled", |
|
| 87 |
- "feature@bookmarks": "enabled", |
|
| 88 |
- "feature@edonr": "enabled", |
|
| 89 |
- "feature@embedded_data": "active", |
|
| 90 |
- "feature@empty_bpobj": "active", |
|
| 91 |
- "feature@enabled_txg": "active", |
|
| 92 |
- "feature@extensible_dataset": "enabled", |
|
| 93 |
- "feature@filesystem_limits": "enabled", |
|
| 94 |
- "feature@hole_birth": "active", |
|
| 95 |
- "feature@large_blocks": "enabled", |
|
| 96 |
- "feature@lz4_compress": "active", |
|
| 97 |
- "feature@multi_vdev_crash_dump": "enabled", |
|
| 98 |
- "feature@sha512": "enabled", |
|
| 99 |
- "feature@skein": "enabled", |
|
| 100 |
- "feature@spacemap_histogram": "active", |
|
| 101 |
- "fragmentation": "3%", |
|
| 102 |
- "free": "46.3G", |
|
| 103 |
- "freeing": "0", |
|
| 104 |
- "guid": "15729052870819522408", |
|
| 105 |
- "health": "ONLINE", |
|
| 106 |
- "leaked": "0", |
|
| 107 |
- "listsnapshots": "off", |
|
| 108 |
- "name": "rpool", |
|
| 109 |
- "readonly": "off", |
|
| 110 |
- "size": "49.8G", |
|
| 111 |
- "version": "-" |
|
| 112 |
- } |
|
| 113 | 67 |
''' |
| 114 | 68 |
|
| 115 | 69 |
from collections import defaultdict |
| ... | ... |
@@ -55,8 +55,8 @@ options: |
| 55 | 55 |
C(ObjectInherit). |
| 56 | 56 |
- For more information on the choices see MSDN InheritanceFlags enumeration |
| 57 | 57 |
at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx). |
| 58 |
- choices: [ ContainerInherit, None, ObjectInherit ] |
|
| 59 |
- default: For Leaf File, 'None'; For Directory, 'ContainerInherit, ObjectInherit'; |
|
| 58 |
+ - Defaults to C(ContainerInherit, ObjectInherit) for Directories. |
|
| 59 |
+ choices: [ ContainerInherit, ObjectInherit ] |
|
| 60 | 60 |
propagation: |
| 61 | 61 |
description: |
| 62 | 62 |
- Propagation flag on the ACL rules. |