Improve reference titles and parmalink titles.

ansible-community · Apr 7, 2024 · c887263 · c887263
1 parent 651c202
commit c887263
Show file tree

Hide file tree

Showing 45 changed files with 119 additions and 149 deletions.
diff --git a/src/antsibull_docs/data/docsite/ansible-docsite/macros/parameters.rst.j2 b/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', role_entrypoint=None) %}
+{% macro in_rst(elements, suboption_key='suboptions', role_entrypoint=None, special=None) %}
 .. tabularcolumns:: \X{1}{3}\X{2}{3}
 
 .. list-table::
@@ -46,6 +46,9 @@
 {%   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'] %}
@@ -178,7 +181,7 @@
 
 {##################################################################################################################}
 
-{% macro in_html(elements, suboption_key='suboptions', 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%">

diff --git a/src/antsibull_docs/data/docsite/ansible-docsite/macros/returnvalues.rst.j2 b/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::
@@ -44,9 +44,9 @@
 {%   for full_key in value['full_keys'] %}
           - @{ full_key | antsibull_to_json }@
 {%   endfor %}
-
-      .. raw:: html
-         :url: data:text/plain;base64,IA==
+{%   if special is not none %}
+        special: @{ special }@
+{%   endif %}
 
       .. ansible-option-type-line::
 
@@ -114,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%">

diff --git a/src/antsibull_docs/data/docsite/ansible-docsite/plugin.rst.j2 b/src/antsibull_docs/data/docsite/ansible-docsite/plugin.rst.j2
@@ -190,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 %}
@@ -212,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 %}
@@ -236,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 %}
@@ -362,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 %}
 
@@ -383,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 %}

diff --git a/src/sphinx_antsibull_ext/directives.py b/src/sphinx_antsibull_ext/directives.py
@@ -244,9 +244,8 @@ def _run(
         rst_id = (
             f"ansible_collections.{content.fqcn}_{content.plugin_type}_requirements"
         )
-        ref_title = (
-            f"Requirements of the {_plugin_name(content.fqcn, content.plugin_type)}"
-        )
+        plugin_name = _plugin_name(content.fqcn, content.plugin_type)
+        ref_title = f"Requirements of the {plugin_name}"
         if content.role_entrypoint is not None and content.plugin_type == "role":
             rst_id = (
                 f"ansible_collections.{content.fqcn}_role"
@@ -278,13 +277,14 @@ def _run(self, content_str: str, content: AnsibleAttribute) -> list[nodes.Node]:
         node = ansible_attribute(
             "", content.name, classes=["ansible-option-title"], ids=[html_id]
         )
+        plugin_name = _plugin_name(content.fqcn, content.plugin_type)
         self.state.document.note_explicit_target(node)
         std = t.cast(StandardDomain, self.env.get_domain("std"))
         std.note_hyperlink_target(
             rst_id,
             self.env.docname,
             html_id,
-            f"{content.name} attribute of {_plugin_name(content.fqcn, content.plugin_type)}",
+            f"{content.name} attribute of {plugin_name}",
         )
         permalink = nodes.raw(
             "",
@@ -309,7 +309,7 @@ def _compile_ids(
     role_entrypoint: str | None,
     full_keys: list[list[str]],
     prefix_type: str,
-) -> tuple[dict[str, tuple[str, str]], list[str]]:
+) -> tuple[dict[str, tuple[str, str, str]], list[str]]:
     rst_id_prefix = f"ansible_collections.{fqcn}_{plugin_type}__{prefix_type}-"
     html_id_prefix = f"{prefix_type}-"
     if role_entrypoint is not None:
@@ -321,7 +321,7 @@ def _compile_ids(
         html_id = html_id_prefix + "/".join([_percent_encode(k) for k in full_key])
         rst_id = rst_id_prefix + "/".join([massage_rst_label(k) for k in full_key])
         html_ids.append(html_id)
-        rst_ids[rst_id] = (html_id, ".".join(full_key))
+        rst_ids[rst_id] = (html_id, ".".join(full_key), ".".join(full_key[1:]))
     return rst_ids, _make_unique(html_ids)
 
 
@@ -342,19 +342,41 @@ def _run(self, content_str: str, content: AnsibleOption) -> list[nodes.Node]:
             classes=["ansible-option-title"],
             ids=html_ids,
         )
+        what_title = "{key} option of"
+        what_perma = "this option"
+        if content.plugin_type in ("lookup", "filter", "test"):
+            what_title = "{key} keyword option of"
+            what_perma = "this keyword option"
+        if content.special == "positional":
+            what_title = "{key} positional option of"
+            what_perma = "this positional option"
+        if content.special == "input":
+            what_title = "input of"
+            what_perma = f"the {content.plugin_type}'s input"
+            if len(content.full_keys[0]) > 1:
+                what_title = "nested input field {subkey} of"
+                what_perma = f"this nested field of the {content.plugin_type}'s input"
+        if content.special == "terms":
+            what_title = "terms for the"
+            what_perma = f"the {content.plugin_type}'s terms"
+            if len(content.full_keys[0]) > 1:
+                what_title = "nested term field {subkey} for the"
+                what_perma = f"this nested field of the {content.plugin_type}'s term"
+        plugin_name = _plugin_name(content.fqcn, content.plugin_type)
         self.state.document.note_explicit_target(node)
         std = t.cast(StandardDomain, self.env.get_domain("std"))
-        for rst_id, (html_id, key) in rst_ids.items():
+        for rst_id, (html_id, key, subkey) in rst_ids.items():
+            rst_title = f"{what_title.format(key=key, subkey=subkey)} {plugin_name}"
             std.note_hyperlink_target(
                 rst_id,
                 self.env.docname,
                 html_id,
-                f"{key} option of {_plugin_name(content.fqcn, content.plugin_type)}",
+                rst_title,
             )
         permalink = nodes.raw(
             "",
             f' <a class="ansibleOptionLink" href="#{html_ids[0]}"'
-            ' title="Permalink to this option"></a>',
+            f' title="Permalink to {what_perma}"></a>',
             format="html",
         )
         return [node, permalink]
@@ -377,19 +399,32 @@ def _run(self, content_str: str, content: AnsibleReturnValue) -> list[nodes.Node
             classes=["ansible-option-title"],
             ids=html_ids,
         )
+        what_title = "{key} return value of"
+        what_perma = "this return value"
+        if content.special == "facts":
+            what_title = "{key} returned fact of"
+            what_perma = "this returned fact"
+        if content.special == "return-value":
+            what_title = "return value of the"
+            what_perma = f"the {content.plugin_type}'s return value"
+            if len(content.full_keys[0]) > 1:
+                what_title = "nested return value field {subkey} of the"
+                what_perma = f"this nested return value of this {content.plugin_type}"
+        plugin_name = _plugin_name(content.fqcn, content.plugin_type)
         self.state.document.note_explicit_target(node)
         std = t.cast(StandardDomain, self.env.get_domain("std"))
-        for rst_id, (html_id, key) in rst_ids.items():
+        for rst_id, (html_id, key, subkey) in rst_ids.items():
+            ref_title = f"{what_title.format(key=key, subkey=subkey)} {plugin_name}"
             std.note_hyperlink_target(
                 rst_id,
                 self.env.docname,
                 html_id,
-                f"{key} return value of {_plugin_name(content.fqcn, content.plugin_type)}",
+                ref_title,
             )
         permalink = nodes.raw(
             "",
             f' <a class="ansibleOptionLink" href="#{html_ids[0]}"'
-            ' title="Permalink to this return value"></a>',
+            f' title="Permalink to {what_perma}"></a>',
             format="html",
         )
         return [node, permalink]

diff --git a/src/sphinx_antsibull_ext/schemas/ansible_plugin.py b/src/sphinx_antsibull_ext/schemas/ansible_plugin.py
@@ -47,6 +47,9 @@ class AnsibleOption(p.BaseModel):
     role_entrypoint: t.Optional[str] = None
     name: str
     full_keys: list[list[str]]
+    special: t.Union[
+        t.Literal["positional"], t.Literal["input"], t.Literal["terms"], None
+    ] = None
 
 
 class AnsibleReturnValue(p.BaseModel):
@@ -55,3 +58,4 @@ class AnsibleReturnValue(p.BaseModel):
     role_entrypoint: t.Optional[str] = None
     name: str
     full_keys: list[list[str]]
+    special: t.Union[t.Literal["facts"], t.Literal["return-value"], None] = None
diff --git a/tests/functional/baseline-default/collections/ns/col2/foo2_module.rst b/tests/functional/baseline-default/collections/ns/col2/foo2_module.rst
@@ -488,9 +488,6 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
         full_keys:
           - ["bar"]
 
-      .. raw:: html
-         :url: data:text/plain;base64,IA==
-
       .. ansible-option-type-line::
 
         :ansible-option-type:`string`

diff --git a/tests/functional/baseline-default/collections/ns2/col/bar_filter.rst b/tests/functional/baseline-default/collections/ns2/col/bar_filter.rst
@@ -98,6 +98,7 @@ This describes the input of the filter, the value before ``| ns2.col.bar``.
         name: "Input"
         full_keys:
           - ["_input"]
+        special: input
 
       .. ansible-option-type-line::
 
@@ -154,6 +155,7 @@ example: ``input | ns2.col.bar(positional1, positional2, ...)``
         name: "foo"
         full_keys:
           - ["foo"]
+        special: positional
 
       .. ansible-option-type-line::
 
@@ -188,6 +190,7 @@ example: ``input | ns2.col.bar(positional1, positional2, ...)``
         name: "bar"
         full_keys:
           - ["bar"]
+        special: positional
 
       .. ansible-option-type-line::
 
@@ -353,9 +356,7 @@ Return Value
         name: "Return value"
         full_keys:
           - ["_value"]
-
-      .. raw:: html
-         :url: data:text/plain;base64,IA==
+        special: return-value
 
       .. ansible-option-type-line::
 

diff --git a/tests/functional/baseline-default/collections/ns2/col/bar_test.rst b/tests/functional/baseline-default/collections/ns2/col/bar_test.rst
@@ -96,6 +96,7 @@ This describes the input of the test, the value before ``is ns2.col.bar`` or ``i
         name: "Input"
         full_keys:
           - ["_input"]
+        special: input
 
       .. ansible-option-type-line::
 
@@ -176,9 +177,7 @@ Return Value
         name: "Return value"
         full_keys:
           - ["_value"]
-
-      .. raw:: html
-         :url: data:text/plain;base64,IA==
+        special: return-value
 
       .. ansible-option-type-line::
 

diff --git a/tests/functional/baseline-default/collections/ns2/col/foo2_module.rst b/tests/functional/baseline-default/collections/ns2/col/foo2_module.rst
@@ -339,9 +339,6 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
         full_keys:
           - ["bar"]
 
-      .. raw:: html
-         :url: data:text/plain;base64,IA==
-
       .. ansible-option-type-line::
 
         :ansible-option-type:`string`

diff --git a/tests/functional/baseline-default/collections/ns2/col/foo_filter.rst b/tests/functional/baseline-default/collections/ns2/col/foo_filter.rst
@@ -98,6 +98,7 @@ This describes the input of the filter, the value before ``| ns2.col.foo``.
         name: "Input"
         full_keys:
           - ["_input"]
+        special: input
 
       .. ansible-option-type-line::
 
@@ -264,9 +265,7 @@ Return Value
         name: "Return value"
         full_keys:
           - ["_value"]
-
-      .. raw:: html
-         :url: data:text/plain;base64,IA==
+        special: return-value
 
       .. ansible-option-type-line::
 

diff --git a/tests/functional/baseline-default/collections/ns2/col/foo_lookup.rst b/tests/functional/baseline-default/collections/ns2/col/foo_lookup.rst
@@ -96,6 +96,7 @@ Terms
         name: "Terms"
         full_keys:
           - ["_terms"]
+        special: terms
 
       .. ansible-option-type-line::
 
@@ -237,9 +238,7 @@ Return Value
         name: "Return value"
         full_keys:
           - ["_raw"]
-
-      .. raw:: html
-         :url: data:text/plain;base64,IA==
+        special: return-value
 
       .. ansible-option-type-line::
 

diff --git a/tests/functional/baseline-default/collections/ns2/col/foo_module.rst b/tests/functional/baseline-default/collections/ns2/col/foo_module.rst
@@ -490,9 +490,6 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
         full_keys:
           - ["bar"]
 
-      .. raw:: html
-         :url: data:text/plain;base64,IA==
-
       .. ansible-option-type-line::
 
         :ansible-option-type:`string`