Add anchor to each parameter row (#66895) (#67057)

* Add anchor to each paramater row
* Update docs/templates/plugin.rst.j2
* Insert full keys into plugin docs.
* Added visible links.

Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit 5b93a14a0f)

Co-authored-by: Dick Visser <dick.visser@geant.org>

docs/templates/plugin.rst.j2

@@ -106,7 +106,7 @@ 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>
@@ -114,6 +114,7 @@ Parameters
                 {# 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 %}
@@ -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 %}
@@ -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 %}

hacking/build_library/build_ansible/command_plugins/plugin_formatter.py

@@ -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))
@@ -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)
 
@@ -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):
 
@@ -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