mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
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
This commit is contained in:
Dag Wieers
scottb
parent
b945846814
commit
80ba7b7402
3 changed files with 74 additions and 68 deletions
38
docs/templates/plugin.rst.j2
vendored
38
docs/templates/plugin.rst.j2
vendored
|
|
@ -107,6 +107,7 @@ Parameters
|
|||
{# default / choices #}
|
||||
<td>
|
||||
<div class="cell-border">
|
||||
{# 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 %}
|
||||
<ul style="list-style-type: circle"><b>Choices:</b>
|
||||
{% if value.default not in value.choices %}
|
||||
<li type="disc"><div style="color: blue"><b>@{ value.default }@</b> ←</div></li>
|
||||
{% endif %}
|
||||
<ul><b>Choices:</b>
|
||||
{% for choice in value.choices %}
|
||||
{% if value.default is defined and choice == value.default %}
|
||||
<li type="disc"><div style="color: blue"><b>@{ value.default }@</b> ←</div></li>
|
||||
{% if (value.default is string and choice == value.default) or (value.default is iterable and choice in value.default) %}
|
||||
<li type="disc"><div style="color: blue"><b>@{ choice | escape }@</b> ←</div></li>
|
||||
{% else %}
|
||||
<li>@{ choice }@</li>
|
||||
<li type="circle">@{ choice | escape }@</li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% elif value.default is defined %}
|
||||
<div style="color: blue">@{ value.default | html_ify }@</div>
|
||||
{% endif %}
|
||||
{# Show default value, when multiple choice or no choices #}
|
||||
{% if value.default is defined and value.default not in value.choices %}
|
||||
<b>Default:</b><br/><div style="color: blue">@{ value.default | escape }@</div>
|
||||
{% endif %}
|
||||
</div>
|
||||
</td>
|
||||
|
|
@ -239,8 +240,7 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a
|
|||
<td>
|
||||
<div class="outer-elbow-container">
|
||||
{% for i in range(1, loop.depth) %}
|
||||
<div class="elbow-placeholder">
|
||||
</div>
|
||||
<div class="elbow-placeholder"></div>
|
||||
{% endfor %}
|
||||
<div class="elbow-key">
|
||||
<b>@{ key }@</b>
|
||||
|
|
@ -248,7 +248,7 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a
|
|||
</div>
|
||||
</div>
|
||||
</td>
|
||||
<td><div class="cell-border">@{ value.returned }@</div></td>
|
||||
<td><div class="cell-border">@{ value.returned | html_ify }@</div></td>
|
||||
<td>
|
||||
<div class="cell-border">
|
||||
{% 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 %}
|
||||
<br/>
|
||||
{% if value.sample %}
|
||||
{% if value.sample is defined and value.sample %}
|
||||
<div style="font-size: smaller"><b>Sample:</b></div>
|
||||
{# <div style="font-size: smaller; color: blue; word-wrap: break-word; overflow-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> #}
|
||||
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div>
|
||||
{# TODO: The sample should be escaped, using | escape or | htmlify, but both mess things up beyond repair with dicts #}
|
||||
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | replace('\n', '\n ') | html_ify }@</div>
|
||||
{% endif %}
|
||||
</div>
|
||||
</td>
|
||||
|
|
@ -313,7 +313,7 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
|
|||
</div>
|
||||
</div>
|
||||
</td>
|
||||
<td><div class="cell-border">@{ value.returned }@</div></td>
|
||||
<td><div class="cell-border">@{ value.returned | html_ify }@</div></td>
|
||||
<td>
|
||||
<div class="cell-border">
|
||||
{% if value.description is string %}
|
||||
|
|
@ -324,10 +324,10 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
|
|||
{% endfor %}
|
||||
{% endif %}
|
||||
<br/>
|
||||
{% if value.sample %}
|
||||
{% if value.sample is defined and value.sample %}
|
||||
<div style="font-size: smaller"><b>Sample:</b></div>
|
||||
{# <div style="font-size: smaller; color: blue; word-wrap: break-word; overflow-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> #}
|
||||
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div>
|
||||
{# TODO: The sample should be escaped, using | escape or | htmlify, but both mess things up beyond repair with dicts #}
|
||||
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | replace('\n', '\n ') | html_ify }@</div>
|
||||
{% endif %}
|
||||
</div>
|
||||
</td>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue