Improve logical information for labels to Ansible objects

src/antsibull_docs/augment_docs.py

@@ -12,13 +12,11 @@
 from collections.abc import Mapping, MutableMapping
 
 from .docs_parsing.routing import CollectionRoutingT
-from .utils.rst import massage_rst_label
 
 
-def add_full_key(
+def add_full_keys(
     options_data: Mapping[str, t.Any],
     suboption_entry: str,
-    _full_key: list[str] | None = None,
     _full_keys: list[list[str]] | None = None,
 ) -> None:
     """
@@ -28,45 +26,35 @@ def add_full_key(
     a deeply nested structure, for instance.)  They describe each entry into the dict.  When
     constructing documentation which uses that, it can be useful to know the hierarchy leads to
     that entry (for instance, to make a target for an html href).  This function adds that
-    information to a ``full_key`` field on the suboptions' entry.
+    information to a ``full_keys`` field on the suboptions' entry.
 
     :arg options_data: The documentation data which is going to be analyzed and updated.
     :arg suboption_entry: The name of the suboptions key in the data.  For options data, this is
         ``suboptions``.  For returndocs, it is ``contains``.
-    :kwarg _full_key: This is a recursive function.  After we pass the first level of nesting,
-        ``_full_key`` is set to record the names of the upper levels of the hierarchy.
     :kwarg _full_keys: This is a recursive function.  After we pass the first level of nesting,
         ``_full_keys`` is a list of sets to record the names of the upper levels of the hierarchy,
         including all aliases for all names involved.
 
     .. warning:: This function operates by side-effect.  The options_data dictionay is modified
         directly.
     """
-    if _full_key is None:
-        _full_key = []
     if _full_keys is None:
         _full_keys = [[]]
 
     for key, entry in options_data.items():
         # Make sure that "full key" is contained
-        full_key_k = _full_key + [key]
         full_keys_k = [fk + [key] for fk in _full_keys]
         if "aliases" in entry:
             for alias in entry["aliases"]:
                 full_keys_k.extend([fk + [alias] for fk in _full_keys])
-        entry["full_key"] = full_key_k
         entry["full_keys"] = full_keys_k
-        entry["full_keys_rst"] = sorted(
-            {tuple(massage_rst_label(p) for p in fk) for fk in full_keys_k}
-        )
 
         # Process suboptions
         suboptions = entry.get(suboption_entry)
         if suboptions:
-            add_full_key(
+            add_full_keys(
                 suboptions,
                 suboption_entry=suboption_entry,
-                _full_key=full_key_k,
                 _full_keys=full_keys_k,
             )
 
@@ -126,7 +114,7 @@ def augment_docs(
     The additional data is calculated from the existing data and then added to the data.
     Current Augmentations:
 
-    * ``full_key`` allows displaying nested suboptions and return dicts.
+    * ``full_keys`` allows displaying nested suboptions and return dicts.
     * In see-alsos that reference to modules or plugins but that have no description,
       automatically insert the destination's short_description (if available)
 
@@ -145,14 +133,14 @@ def augment_docs(
         # Now augment all plugin records
         for plugin_name, plugin_record in plugin_map.items():
             if plugin_record.get("return"):
-                add_full_key(plugin_record["return"], "contains")
+                add_full_keys(plugin_record["return"], "contains")
             if plugin_record.get("doc"):
-                add_full_key(plugin_record["doc"]["options"], "suboptions")
+                add_full_keys(plugin_record["doc"]["options"], "suboptions")
                 if plugin_record["doc"].get("seealso"):
                     _add_seealso(plugin_record["doc"]["seealso"], plugin_info)
                 _add_aliases(
                     plugin_name, plugin_record["doc"], routing_sources[plugin_name]
                 )
             if plugin_record.get("entry_points"):
                 for entry_point in plugin_record["entry_points"].values():
-                    add_full_key(entry_point["options"], "options")
+                    add_full_keys(entry_point["options"], "options")

src/antsibull_docs/data/docsite/ansible-docsite/macros/attributes.rst.j2

@@ -24,17 +24,15 @@
   * - .. raw:: html
 
         <div class="ansible-option-cell">
-        <div class="ansibleOptionAnchor" id="attribute-@{ parameter_html_prefix }@@{ attribute | e }@"></div>
 
-      .. _@{ rst_attribute_ref(plugin_name, plugin_type, role_entrypoint=role_entrypoint, attribute=attribute) }@:
+      .. ansible-attribute::
 
-      .. rst-class:: ansible-option-title
-
-      **@{ attribute }@**
-
-      .. raw:: html
-
-        <a class="ansibleOptionLink" href="#attribute-@{ parameter_html_prefix }@@{ attribute | e }@" title="Permalink to this attribute"></a>
+        fqcn: @{ plugin_name }@
+        plugin_type: @{ plugin_type }@
+{%   if role_entrypoint is not none %}
+        role_entrypoint: @{ role_entrypoint | antsibull_to_json }@
+{%   endif %}
+        name: @{ attribute | antsibull_to_json }@
 
       .. raw:: html
 

src/antsibull_docs/data/docsite/ansible-docsite/macros/parameters.rst.j2

@@ -10,7 +10,7 @@
 {% from 'macros/deprecates.rst.j2' import in_html as deprecates_html with context %}
 {% from 'macros/version_added.rst.j2' import version_added_rst, version_added_html %}
 
-{% macro in_rst(elements, suboption_key='suboptions', parameter_html_prefix='', role_entrypoint=None) %}
+{% macro in_rst(elements, suboption_key='suboptions', role_entrypoint=None, special=None) %}
 .. tabularcolumns:: \X{1}{3}\X{2}{3}
 
 .. list-table::
@@ -27,27 +27,28 @@
   * - .. raw:: html
 
         {% for i in range(1, loop.depth) %}<div class="ansible-option-indent"></div>{% endfor %}<div class="ansible-option-cell">
-{% for full_key in value['full_keys'] %}
-        <div class="ansibleOptionAnchor" id="parameter-@{ parameter_html_prefix }@{% for part in full_key %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}"></div>
-{% endfor %}
-{% if loop.depth > 1 %}
+{%   if loop.depth > 1 %}
 
       .. raw:: latex
 
         \hspace{@{ 0.02 * loop.depth0 }@\textwidth}\begin{minipage}[t]{@{ 0.32 - 0.02 * loop.depth0 }@\textwidth}
-{% endif %}
-
-{% for full_key in value['full_keys_rst'] %}
-      .. _@{ rst_option_ref(plugin_name, plugin_type, role_entrypoint=role_entrypoint, option=full_key) }@:
-{% endfor %}
-
-      .. rst-class:: ansible-option-title
-
-      **@{ key }@**
+{%   endif %}
 
-      .. raw:: html
+      .. ansible-option::
 
-        <a class="ansibleOptionLink" href="#parameter-@{ parameter_html_prefix }@{% for part in value['full_key'] %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this option"></a>
+        fqcn: @{ plugin_name }@
+        plugin_type: @{ plugin_type }@
+{%   if role_entrypoint is not none %}
+        role_entrypoint: @{ role_entrypoint | antsibull_to_json }@
+{%   endif %}
+        name: @{ key | antsibull_to_json }@
+        full_keys:
+{%   for full_key in value['full_keys'] %}
+          - @{ full_key | antsibull_to_json }@
+{%   endfor %}
+{%   if special is not none %}
+        special: @{ special }@
+{%   endif %}
 
       .. ansible-option-type-line::
 {%   if value['aliases'] %}
@@ -180,7 +181,7 @@
 
 {##################################################################################################################}
 
-{% macro in_html(elements, suboption_key='suboptions', parameter_html_prefix='', role_entrypoint=None) %}
+{% macro in_html(elements, suboption_key='suboptions', role_entrypoint=None, special=None) %}
 .. raw:: html
 
   <table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
@@ -197,10 +198,10 @@
   <tr class="row-@{ row_class.next() }@">
     <td>{% for i in range(1, loop.depth) %}<div class="ansible-option-indent"></div>{% endfor %}<div class="ansible-option-cell">
 {%   for full_key in value['full_keys'] %}
-      <div class="ansibleOptionAnchor" id="parameter-@{ parameter_html_prefix }@{% for part in full_key %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}"></div>
+      <div class="ansibleOptionAnchor" id="parameter-{% if entry_point is not none %}@{ entry_point }@--{% endif %}{% for part in full_key %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}"></div>
 {%   endfor %}
-      <p class="ansible-option-title"><strong>@{ key | escape }@</strong></p>
-      <a class="ansibleOptionLink" href="#parameter-@{ parameter_html_prefix }@{% for part in value['full_key'] %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this option"></a>
+      <strong class="ansible-option-title">@{ key | escape }@</strong>
+      <a class="ansibleOptionLink" href="#parameter-{% if entry_point is not none %}@{ entry_point }@--{% endif %}{% for part in value['full_keys'][0] %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this option"></a>
 {%   if value['aliases'] %}
       <p class="ansible-option-type-line"><span class="ansible-option-aliases">aliases: @{ value['aliases']|join(', ') }@</span></p>
 {%   endif %}

src/antsibull_docs/data/docsite/ansible-docsite/macros/returnvalues.rst.j2

@@ -8,7 +8,7 @@
 {% from 'macros/choiceslist.rst.j2' import in_html as choices_html %}
 {% from 'macros/version_added.rst.j2' import version_added_rst, version_added_html %}
 
-{% macro in_rst(elements, role_entrypoint=None) %}
+{% macro in_rst(elements, role_entrypoint=None, special=None) %}
 .. tabularcolumns:: \X{1}{3}\X{2}{3}
 
 .. list-table::
@@ -25,27 +25,28 @@
   * - .. raw:: html
 
         {% for i in range(1, loop.depth) %}<div class="ansible-option-indent"></div>{% endfor %}<div class="ansible-option-cell">
-{% for full_key in value['full_keys'] %}
-        <div class="ansibleOptionAnchor" id="return-{% for part in full_key %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}"></div>
-{% endfor %}
-{% if loop.depth > 1 %}
+{%   if loop.depth > 1 %}
 
       .. raw:: latex
 
         \hspace{@{ 0.02 * loop.depth0 }@\textwidth}\begin{minipage}[t]{@{ 0.32 - 0.02 * loop.depth0 }@\textwidth}
-{% endif %}
-
-{% for full_key in value['full_keys_rst'] %}
-      .. _@{ rst_return_value_ref(plugin_name, plugin_type, role_entrypoint=role_entrypoint, return_value=full_key) }@:
-{% endfor %}
-
-      .. rst-class:: ansible-option-title
-
-      **@{ key }@**
+{%   endif %}
 
-      .. raw:: html
+      .. ansible-return-value::
 
-        <a class="ansibleOptionLink" href="#return-{% for part in value['full_key'] %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this return value"></a>
+        fqcn: @{ plugin_name }@
+        plugin_type: @{ plugin_type }@
+{%   if role_entrypoint is not none %}
+        role_entrypoint: @{ role_entrypoint | antsibull_to_json }@
+{%   endif %}
+        name: @{ key | antsibull_to_json }@
+        full_keys:
+{%   for full_key in value['full_keys'] %}
+          - @{ full_key | antsibull_to_json }@
+{%   endfor %}
+{%   if special is not none %}
+        special: @{ special }@
+{%   endif %}
 
       .. ansible-option-type-line::
 
@@ -113,7 +114,7 @@
 
 {##################################################################################################################}
 
-{% macro in_html(elements, role_entrypoint=None) %}
+{% macro in_html(elements, role_entrypoint=None, special=None) %}
 .. raw:: html
 
   <table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
@@ -132,8 +133,8 @@
 {%   for full_key in value['full_keys'] %}
       <div class="ansibleOptionAnchor" id="return-{% for part in full_key %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}"></div>
 {%   endfor %}
-      <p class="ansible-option-title"><strong>@{ key | escape }@</strong></p>
-      <a class="ansibleOptionLink" href="#return-{% for part in value['full_key'] %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this return value"></a>
+      <strong class="ansible-option-title">@{ key | escape }@</strong>
+      <a class="ansibleOptionLink" href="#return-{% for part in value['full_keys'][0] %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this return value"></a>
       <p class="ansible-option-type-line">
         <span class="ansible-option-type">@{ value['type'] | documented_type }@</span>
 {%   if value['type'] == 'list' and value['elements'] is not none %}

src/antsibull_docs/data/docsite/ansible-docsite/plugin-error.rst.j2

@@ -27,6 +27,10 @@
 @{ title }@
 @{ '+' * title|column_width }@
 
+.. ansible-plugin::
+
+  fqcn: @{ plugin_name }@
+  plugin_type: @{ plugin_type }@
 
 The documentation for the @{ plugin_type }@ plugin, @{ plugin_name }@,  was malformed.
 

src/antsibull_docs/data/docsite/ansible-docsite/plugin-redirect.rst.j2

@@ -22,6 +22,11 @@
 @{ title }@
 @{ '+' * title|column_width }@
 
+.. ansible-plugin::
+
+  fqcn: @{ plugin_name }@
+  plugin_type: @{ plugin_type }@
+
 .. Collection note
 
 {% if collection == 'ansible.builtin' -%}

src/antsibull_docs/data/docsite/ansible-docsite/plugin-tombstone.rst.j2

@@ -20,6 +20,11 @@
 @{ plugin_name }@
 @{ '+' * plugin_name|column_width }@
 
+.. ansible-plugin::
+
+  fqcn: @{ plugin_name }@
+  plugin_type: @{ plugin_type }@
+
 .. Collection note
 
 {% if collection == 'ansible.builtin' -%}

src/antsibull_docs/data/docsite/ansible-docsite/plugin.rst.j2

@@ -50,6 +50,14 @@
 @{ title }@
 @{ '+' * title|column_width }@
 
+.. ansible-plugin::
+
+  fqcn: @{ plugin_name }@
+  plugin_type: @{ plugin_type }@
+{% if doc['short_description'] %}
+  short_description: @{ doc['short_description'] | rst_ify | antsibull_to_json }@
+{% endif %}
+
 .. Collection note
 
 {% if collection == 'ansible.builtin' -%}
@@ -150,10 +158,14 @@ Aliases: @{ ', '.join(doc['aliases'] | sort) }@
 .. Requirements
 
 {% if doc['requirements'] -%}
-.. _@{ rst_requirements_ref(plugin_name, plugin_type) }@:
-
 Requirements
 ------------
+
+.. ansible-requirements-anchor::
+
+  fqcn: @{ plugin_name }@
+  plugin_type: @{ plugin_type }@
+
 {%   if plugin_type in ('module', 'module_util') %}
 The below requirements are needed on the host that executes this @{ plugin_type }@.
 {%   else %}
@@ -178,9 +190,9 @@ Terms
 -----
 
 {%   if use_html_blobs %}
-@{     parameters_html([['Terms', doc['options']['_terms']]], suboption_key='suboptions') }@
+@{     parameters_html([['Terms', doc['options']['_terms']]], suboption_key='suboptions', special='terms') }@
 {%   else %}
-@{     parameters_rst([['Terms', doc['options']['_terms']]], suboption_key='suboptions') }@
+@{     parameters_rst([['Terms', doc['options']['_terms']]], suboption_key='suboptions', special='terms') }@
 {%   endif %}
 
 {% endif %}
@@ -200,9 +212,9 @@ This describes the input of the test, the value before ``is @{plugin_name}@`` or
 {%   endif %}
 
 {%   if use_html_blobs %}
-@{     parameters_html([['Input', doc['options']['_input']]], suboption_key='suboptions') }@
+@{     parameters_html([['Input', doc['options']['_input']]], suboption_key='suboptions', special='input') }@
 {%   else %}
-@{     parameters_rst([['Input', doc['options']['_input']]], suboption_key='suboptions') }@
+@{     parameters_rst([['Input', doc['options']['_input']]], suboption_key='suboptions', special='input') }@
 {%   endif %}
 
 {% endif %}
@@ -224,9 +236,9 @@ examples: ``input is @{plugin_name}@(positional1, positional2, ...)`` and ``inpu
 {%   endif %}
 
 {%   if use_html_blobs %}
-@{     parameters_html(doc['options'] | extract_options_from_list(doc['positional'], options_to_ignore=['_input']), suboption_key='suboptions') }@
+@{     parameters_html(doc['options'] | extract_options_from_list(doc['positional'], options_to_ignore=['_input']), suboption_key='suboptions', special='positional') }@
 {%   else %}
-@{     parameters_rst(doc['options'] | extract_options_from_list(doc['positional'], options_to_ignore=['_input']), suboption_key='suboptions') }@
+@{     parameters_rst(doc['options'] | extract_options_from_list(doc['positional'], options_to_ignore=['_input']), suboption_key='suboptions', special='positional') }@
 {%   endif %}
 
 {% endif %}
@@ -350,9 +362,9 @@ Returned Facts
 Facts returned by this module are added/updated in the ``hostvars`` host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them.
 
 {%   if use_html_blobs %}
-@{     return_docs_html(returnfacts | dictsort) }@
+@{     return_docs_html(returnfacts | dictsort, special='facts') }@
 {%   else %}
-@{     return_docs_rst(returnfacts | dictsort) }@
+@{     return_docs_rst(returnfacts | dictsort, special='facts') }@
 {%   endif %}
 {% endif %}
 
@@ -371,9 +383,9 @@ Return Value
 
 {%   if plugin_type in ['lookup', 'filter', 'test'] and returndocs | length == 1 and (returndocs | first).startswith('_') %}
 {%     if use_html_blobs %}
-@{       return_docs_html([['Return value', returndocs.values() | first]]) }@
+@{       return_docs_html([['Return value', returndocs.values() | first]], special='return-value') }@
 {%     else %}
-@{       return_docs_rst([['Return value', returndocs.values() | first]]) }@
+@{       return_docs_rst([['Return value', returndocs.values() | first]], special='return-value') }@
 {%     endif %}
 {%   else %}
 {%     if use_html_blobs %}