Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add anchor to each parameter row #66895

Merged
merged 4 commits into from
Feb 3, 2020
Merged

Add anchor to each parameter row #66895

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
54a2099
Add anchor to each paramater row
dnmvisser Jan 29, 2020
7c76e38
Update docs/templates/plugin.rst.j2
dnmvisser Jan 30, 2020
ff2d50c
Insert full keys into plugin docs.
felixfontein Jan 31, 2020
03be4f6
Added visible links.
felixfontein Jan 31, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/docsite/_static/ansible.css
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

9 changes: 6 additions & 3 deletions docs/templates/plugin.rst.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,14 +106,15 @@ Parameters
<th width="100%">Comments</th>
</tr>
{% for key, value in options|dictsort recursive %}
<tr>
<tr id="parameter-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}">
{# indentation based on nesting level #}
{% for i in range(1, loop.depth) %}
<td class="elbow-placeholder"></td>
{% endfor %}
{# parameter name with required and/or introduced label #}
<td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">
<b>@{ key }@</b>
<a class="ansibleOptionLink" href="#parameter-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this option">¶</a>
<div style="font-size: small">
<span style="color: purple">@{ value.type | documented_type }@</span>
{% if value.get('elements') %} / <span style="color: purple">elements=@{ value.elements | documented_type }@</span>{% endif %}
Expand Down Expand Up @@ -282,12 +283,13 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a
<th width="100%">Description</th>
</tr>
{% for key, value in returnfacts|dictsort recursive %}
<tr>
<tr id="return-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}">
{% for i in range(1, loop.depth) %}
<td class="elbow-placeholder"></td>
{% endfor %}
<td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@" colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">
<b>@{ key }@</b>
<a class="ansibleOptionLink" href="#return-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this fact">¶</a>
<div style="font-size: small">
<span style="color: purple">@{ value.type | documented_type }@</span>
{% if value.elements %} / <span style="color: purple">elements=@{ value.elements | documented_type }@</span>{% endif %}
Expand Down Expand Up @@ -357,12 +359,13 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
<th width="100%">Description</th>
</tr>
{% for key, value in returndocs|dictsort recursive %}
<tr>
<tr id="return-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}">
{% for i in range(1, loop.depth) %}
<td class="elbow-placeholder">&nbsp;</td>
{% endfor %}
<td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">
<b>@{ key }@</b>
<a class="ansibleOptionLink" href="#return-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this return value">¶</a>
<div style="font-size: small">
<span style="color: purple">@{ value.type | documented_type }@</span>
{% if value.elements %} / <span style="color: purple">elements=@{ value.elements | documented_type }@</span>{% endif %}
Expand Down
32 changes: 29 additions & 3 deletions hacking/build_library/build_ansible/command_plugins/plugin_formatter.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,11 +346,17 @@ def too_old(added):
return added_float < TOO_OLD_TO_BE_NOTABLE


def process_options(module, options):
def process_options(module, options, full_key=None):
option_names = []
if full_key is None:
full_key = []

if options:
for (k, v) in iteritems(options):
# Make sure that "full key" is contained
full_key_k = full_key + [k]
v['full_key'] = full_key_k

# Error out if there's no description
if 'description' not in v:
raise AnsibleError("Missing required description for parameter '%s' in '%s' " % (k, module))
Expand All @@ -376,9 +382,9 @@ def process_options(module, options):

if 'suboptions' in v and v['suboptions']:
if isinstance(v['suboptions'], dict):
process_options(module, v['suboptions'])
process_options(module, v['suboptions'], full_key=full_key_k)
elif isinstance(v['suboptions'][0], dict):
process_options(module, v['suboptions'][0])
process_options(module, v['suboptions'][0], full_key=full_key_k)

option_names.append(k)

Expand All @@ -387,6 +393,25 @@ def process_options(module, options):
return option_names


def process_returndocs(returndocs, full_key=None):
if full_key is None:
full_key = []

if returndocs:
for (k, v) in iteritems(returndocs):
# Make sure that "full key" is contained
full_key_k = full_key + [k]
v['full_key'] = full_key_k

# Process suboptions
suboptions = v.get('contains')
if suboptions:
if isinstance(suboptions, dict):
process_returndocs(suboptions, full_key=full_key_k)
elif is_sequence(suboptions):
process_returndocs(suboptions[0], full_key=full_key_k)


def process_plugins(module_map, templates, outputname, output_dir, ansible_version, plugin_type):
for module_index, module in enumerate(module_map):

Expand Down Expand Up @@ -483,6 +508,7 @@ def process_plugins(module_map, templates, outputname, output_dir, ansible_versi
if module_map[module]['returndocs']:
try:
doc['returndocs'] = yaml.safe_load(module_map[module]['returndocs'])
process_returndocs(doc['returndocs'])
except Exception as e:
print("%s:%s:yaml error:%s:returndocs=%s" % (fname, module, e, module_map[module]['returndocs']))
doc['returndocs'] = None
Expand Down