Insert anchor to requirements section programmatically.

Author: felixfontein

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

@@ -158,10 +158,14 @@ Aliases: @{ ', '.join(doc['aliases'] | sort) }@
 .. Requirements
 
 {% if doc['requirements'] -%}
-.. _ansible_collections.@{plugin_name}@_@{plugin_type}@_requirements:
-
 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 %}

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

@@ -130,6 +130,13 @@ Synopsis
 {%   if ep_doc['requirements'] -%}
 Requirements
 ^^^^^^^^^^^^
+
+.. ansible-requirements-anchor::
+
+  fqcn: @{ plugin_name }@
+  plugin_type: role
+  entrypoint: @{ entry_point }@
+
 The below requirements are needed on the remote host and/or the local controller node.
 
 {%     for req in ep_doc['requirements'] %}

src/sphinx_antsibull_ext/directives.py

@@ -32,6 +32,7 @@
     AnsibleAttribute,
     AnsibleOption,
     AnsiblePlugin,
+    AnsibleRequirementsAnchor,
     AnsibleReturnValue,
     AnsibleRoleEntrypoint,
 )
@@ -219,6 +220,48 @@ def _run(
         return [indexnode]
 
 
+def _plugin_name(fqcn: str, plugin_type: str) -> str:
+    if plugin_type in ("module", "role"):
+        return f"{fqcn} {plugin_type}"
+    return f"{fqcn} {plugin_type} plugin"
+
+
+class _RequirementsAnchor(YAMLDirective[AnsibleRequirementsAnchor]):
+    schema = AnsibleRequirementsAnchor
+
+    def _run(
+        self, content_str: str, content: AnsibleRequirementsAnchor
+    ) -> list[nodes.Node]:
+        section = self.state.parent
+        titles = [child for child in section.children if isinstance(child, nodes.title)]
+        if len(titles) != 1:
+            raise self.error(
+                f"Cannot find single title for section {section} - found {titles}"
+            )
+        title = titles[0]
+        self.state.document.note_explicit_target(title)
+        std = t.cast(StandardDomain, self.env.get_domain("std"))
+        rst_id = (
+            f"ansible_collections.{content.fqcn}_{content.plugin_type}_requirements"
+        )
+        ref_title = (
+            f"Requirements of the {_plugin_name(content.fqcn, content.plugin_type)}"
+        )
+        if content.role_entrypoint is not None and content.plugin_type == "role":
+            rst_id = (
+                f"ansible_collections.{content.fqcn}_role"
+                f"-{content.role_entrypoint}_requirements"
+            )
+            ref_title = f"{ref_title}, {content.role_entrypoint} entrypoint"
+        std.note_hyperlink_target(
+            rst_id,
+            self.env.docname,
+            title["ids"][0],
+            ref_title,
+        )
+        return []
+
+
 def _percent_encode(s):
     return _urllib_quote(s, safe="")
 
@@ -241,7 +284,7 @@ def _run(self, content_str: str, content: AnsibleAttribute) -> list[nodes.Node]:
             rst_id,
             self.env.docname,
             html_id,
-            f"{content.name} attribute of {content.fqcn} {content.plugin_type}",
+            f"{content.name} attribute of {_plugin_name(content.fqcn, content.plugin_type)}",
         )
         permalink = nodes.raw(
             "",
@@ -306,7 +349,7 @@ def _run(self, content_str: str, content: AnsibleOption) -> list[nodes.Node]:
                 rst_id,
                 self.env.docname,
                 html_id,
-                f"{key} option of {content.fqcn} {content.plugin_type}",
+                f"{key} option of {_plugin_name(content.fqcn, content.plugin_type)}",
             )
         permalink = nodes.raw(
             "",
@@ -341,7 +384,7 @@ def _run(self, content_str: str, content: AnsibleReturnValue) -> list[nodes.Node
                 rst_id,
                 self.env.docname,
                 html_id,
-                f"{key} return value of {content.fqcn} {content.plugin_type}",
+                f"{key} return value of {_plugin_name(content.fqcn, content.plugin_type)}",
             )
         permalink = nodes.raw(
             "",
@@ -357,6 +400,7 @@ def _run(self, content_str: str, content: AnsibleReturnValue) -> list[nodes.Node
     "ansible-links": _Links,
     "ansible-plugin": _Plugin,
     "ansible-role-entrypoint": _RoleEntrypoint,
+    "ansible-requirements-anchor": _RequirementsAnchor,
     "ansible-attribute": _Attribute,
     "ansible-option": _Option,
     "ansible-return-value": _ReturnValue,

src/sphinx_antsibull_ext/schemas/ansible_plugin.py

@@ -28,6 +28,12 @@ class AnsibleRoleEntrypoint(p.BaseModel):
     short_description: t.Optional[str] = None
 
 
+class AnsibleRequirementsAnchor(p.BaseModel):
+    fqcn: str
+    plugin_type: str
+    role_entrypoint: t.Optional[str] = None
+
+
 class AnsibleAttribute(p.BaseModel):
     fqcn: str
     plugin_type: str

tests/functional/baseline-default/collections/ns/col2/foo2_module.rst

@@ -68,10 +68,14 @@ Synopsis
 
 .. Requirements
 
-.. _ansible_collections.ns.col2.foo2_module_requirements:
-
 Requirements
 ------------
+
+.. ansible-requirements-anchor::
+
+  fqcn: ns.col2.foo2
+  plugin_type: module
+
 The below requirements are needed on the host that executes this module.
 
 - Foo.

tests/functional/baseline-default/collections/ns/col2/foo3_module.rst

@@ -63,10 +63,14 @@ Synopsis
 
 .. Requirements
 
-.. _ansible_collections.ns.col2.foo3_module_requirements:
-
 Requirements
 ------------
+
+.. ansible-requirements-anchor::
+
+  fqcn: ns.col2.foo3
+  plugin_type: module
+
 The below requirements are needed on the host that executes this module.
 
 - Foo.

tests/functional/baseline-default/collections/ns2/col/foo_module.rst

@@ -70,10 +70,14 @@ Aliases: foo_redirect
 
 .. Requirements
 
-.. _ansible_collections.ns2.col.foo_module_requirements:
-
 Requirements
 ------------
+
+.. ansible-requirements-anchor::
+
+  fqcn: ns2.col.foo
+  plugin_type: module
+
 The below requirements are needed on the host that executes this module.
 
 - Foo on remote.

tests/functional/baseline-default/collections/ns2/col/foo_vars.rst

@@ -68,10 +68,14 @@ Synopsis
 
 .. Requirements
 
-.. _ansible_collections.ns2.col.foo_vars_requirements:
-
 Requirements
 ------------
+
+.. ansible-requirements-anchor::
+
+  fqcn: ns2.col.foo
+  plugin_type: vars
+
 The below requirements are needed on the local controller node that executes this vars.
 
 - Enabled in Ansible's configuration.

tests/functional/baseline-no-breadcrumbs/collections/ns/col2/foo2_module.rst

@@ -68,10 +68,14 @@ Synopsis
 
 .. Requirements
 
-.. _ansible_collections.ns.col2.foo2_module_requirements:
-
 Requirements
 ------------
+
+.. ansible-requirements-anchor::
+
+  fqcn: ns.col2.foo2
+  plugin_type: module
+
 The below requirements are needed on the host that executes this module.
 
 - Foo.

tests/functional/baseline-no-breadcrumbs/collections/ns/col2/foo3_module.rst

@@ -63,10 +63,14 @@ Synopsis
 
 .. Requirements
 
-.. _ansible_collections.ns.col2.foo3_module_requirements:
-
 Requirements
 ------------
+
+.. ansible-requirements-anchor::
+
+  fqcn: ns.col2.foo3
+  plugin_type: module
+
 The below requirements are needed on the host that executes this module.
 
 - Foo.