1
0
Fork 0
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 2018-03-12 21:50:52 +01:00 committed by scottb
parent b945846814
commit 80ba7b7402
3 changed files with 74 additions and 68 deletions

View file

@ -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>&nbsp;&larr;</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>&nbsp;&larr;</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>&nbsp;&larr;</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>

View file

@ -49,22 +49,18 @@ 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 = '''
name:
description: ZFS pool name
ansible_facts:
description: Dictionary containing all the detailed information about the ZFS pool facts
returned: always
type: string
sample: rpool
parsable:
description: if parsable output should be provided in machine friendly format.
returned: if 'parsable' is set to True
type: boolean
sample: True
zfs_pools:
type: complex
contains:
ansible_zfs_pools:
description: ZFS pool facts
returned: always
type: string
@ -110,6 +106,16 @@ zfs_pools:
"size": "49.8G",
"version": "-"
}
name:
description: ZFS pool name
returned: always
type: string
sample: rpool
parsable:
description: if parsable output should be provided in machine friendly format.
returned: if 'parsable' is set to True
type: boolean
sample: True
'''
from collections import defaultdict

View file

@ -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.