Move label generating code to one place (#269)

* Move label generating code to one place.

* Address other labels. Fix wrong/ambiguous labels used.

* Also make HTML anchor unambiguous.

* Fix internal option/return value links for simplified RST output.

Author: felixfontein

changelogs/fragments/269-refs.yml

@@ -0,0 +1,3 @@
+bugfixes:
+  - "Fix internal links to options and return values in simplified RST output (https://github.com/ansible-community/antsibull-docs/pull/269)."
+  - "Include role in role attribute references (https://github.com/ansible-community/antsibull-docs/pull/269)."

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

@@ -6,7 +6,7 @@
 
 {% from 'macros/version_added.rst.j2' import version_added_rst %}
 
-{% macro in_rst(attributes, role_entrypoint=None) %}
+{% macro in_rst(attributes, attribute_html_prefix='', role_entrypoint=None) %}
 .. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10}
 
 .. list-table::
@@ -24,17 +24,17 @@
   * - .. raw:: html
 
         <div class="ansible-option-cell">
-        <div class="ansibleOptionAnchor" id="attribute-@{ attribute | e }@"></div>
+        <div class="ansibleOptionAnchor" id="attribute-@{ parameter_html_prefix }@@{ attribute | e }@"></div>
 
-      .. _ansible_collections.@{plugin_name}@_@{plugin_type}@__attribute-@{ attribute }@:
+      .. _@{ rst_attribute_ref(plugin_name, plugin_type, role_entrypoint=role_entrypoint, attribute=attribute) }@:
 
       .. rst-class:: ansible-option-title
 
       **@{ attribute }@**
 
       .. raw:: html
 
-        <a class="ansibleOptionLink" href="#attribute-@{ attribute | e }@" title="Permalink to this attribute"></a>
+        <a class="ansibleOptionLink" href="#attribute-@{ parameter_html_prefix }@@{ attribute | e }@" title="Permalink to this attribute"></a>
 
       .. 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='', parameter_rst_prefix='', role_entrypoint=None) %}
+{% macro in_rst(elements, suboption_key='suboptions', parameter_html_prefix='', role_entrypoint=None) %}
 .. tabularcolumns:: \X{1}{3}\X{2}{3}
 
 .. list-table::
@@ -38,7 +38,7 @@
 {% endif %}
 
 {% for full_key in value['full_keys_rst'] %}
-      .. _ansible_collections.@{plugin_name}@_@{plugin_type}@__parameter-@{ parameter_rst_prefix }@{% for part in full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}:
+      .. _@{ rst_option_ref(plugin_name, plugin_type, role_entrypoint=role_entrypoint, option=full_key) }@:
 {% endfor %}
 
       .. rst-class:: ansible-option-title
@@ -180,7 +180,7 @@
 
 {##################################################################################################################}
 
-{% macro in_html(elements, suboption_key='suboptions', parameter_html_prefix='', parameter_rst_prefix='', role_entrypoint=None) %}
+{% macro in_html(elements, suboption_key='suboptions', parameter_html_prefix='', role_entrypoint=None) %}
 .. raw:: html
 
   <table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">

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

@@ -36,7 +36,7 @@
 {% endif %}
 
 {% for full_key in value['full_keys_rst'] %}
-      .. _ansible_collections.@{plugin_name}@_@{plugin_type}@__return-{% for part in full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}:
+      .. _@{ rst_return_value_ref(plugin_name, plugin_type, role_entrypoint=role_entrypoint, return_value=full_key) }@:
 {% endfor %}
 
       .. rst-class:: ansible-option-title

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

@@ -18,7 +18,7 @@
 
 .. Anchors
 
-.. _ansible_collections.@{plugin_name}@_@{plugin_type}@:
+.. _@{ rst_plugin_ref(plugin_name, plugin_type) }@:
 
 .. Title
 

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

@@ -13,7 +13,7 @@
 
 .. Anchors
 
-.. _ansible_collections.@{plugin_name}@_@{plugin_type}@:
+.. _@{ rst_plugin_ref(plugin_name, plugin_type) }@:
 
 .. Title
 

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

@@ -13,7 +13,7 @@
 
 .. Anchors
 
-.. _ansible_collections.@{plugin_name}@_@{plugin_type}@:
+.. _@{ rst_plugin_ref(plugin_name, plugin_type) }@:
 
 .. Title
 

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

@@ -30,7 +30,7 @@
 
 .. Anchors
 
-.. _ansible_collections.@{plugin_name}@_@{plugin_type}@:
+.. _@{ rst_plugin_ref(plugin_name, plugin_type) }@:
 
 .. Anchors: short name for ansible.builtin
 
@@ -76,7 +76,7 @@
     To install it, use: @{ collection | collection_install | rst_code }@.
 {%   if doc['requirements'] %}
     You need further requirements to be able to use this {% if plugin_type == 'module' %}module{% else %}@{ plugin_type }@ plugin{% endif %},
-    see :ref:`Requirements <ansible_collections.@{plugin_name}@_@{plugin_type}@_requirements>` for details.
+    see :ref:`Requirements <@{ rst_requirements_ref(plugin_name, plugin_type) }@>` for details.
 {%   endif %}
 
     To use it in a playbook, specify: :code:`@{plugin_name}@`.
@@ -150,7 +150,7 @@ Aliases: @{ ', '.join(doc['aliases'] | sort) }@
 .. Requirements
 
 {% if doc['requirements'] -%}
-.. _ansible_collections.@{plugin_name}@_@{plugin_type}@_requirements:
+.. _@{ rst_requirements_ref(plugin_name, plugin_type) }@:
 
 Requirements
 ------------

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

@@ -25,7 +25,7 @@
 
 .. Anchors
 
-.. _ansible_collections.@{plugin_name}@_@{plugin_type}@:
+.. _@{ rst_plugin_ref(plugin_name, plugin_type) }@:
 
 .. Title
 
@@ -130,9 +130,9 @@ Parameters
 ^^^^^^^^^^
 
 {%     if use_html_blobs %}
-@{       parameters_html(ep_doc['options'] | dictsort, suboption_key='options', parameter_html_prefix=entry_point ~ '--', parameter_rst_prefix=entry_point ~ '__', role_entrypoint=entry_point) }@
+@{       parameters_html(ep_doc['options'] | dictsort, suboption_key='options', parameter_html_prefix=entry_point ~ '--', role_entrypoint=entry_point) }@
 {%     else %}
-@{       parameters_rst(ep_doc['options'] | dictsort, suboption_key='options', parameter_html_prefix=entry_point ~ '--', parameter_rst_prefix=entry_point ~ '__', role_entrypoint=entry_point) }@
+@{       parameters_rst(ep_doc['options'] | dictsort, suboption_key='options', parameter_html_prefix=entry_point ~ '--', role_entrypoint=entry_point) }@
 {%     endif %}
 {%   endif %}
 
@@ -143,7 +143,7 @@ Parameters
 Attributes
 ----------
 
-@{     attributes_rst(ep_doc['attributes'], role_entrypoint=entry_point) }@
+@{     attributes_rst(ep_doc['attributes'], attribute_html_prefix=entry_point ~ '--', role_entrypoint=entry_point) }@
 {%   endif %}
 
 .. Notes

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

@@ -17,7 +17,7 @@
 {% for attribute, data in attributes | dictsort %}
 {#   attribute name #}
 
-  * - .. _ansible_collections.@{plugin_name}@_@{plugin_type}@__attribute-@{ attribute }@:
+  * - .. _@{ rst_attribute_ref(plugin_name, plugin_type, role_entrypoint=role_entrypoint, attribute=attribute) }@:
 
       **@{ attribute }@**
 

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

@@ -8,7 +8,7 @@
 {% from 'macros/deprecates.rst.j2' import in_html as deprecates_html with context %}
 {% from 'macros/version_added.rst.j2' import version_added_html %}
 
-{% macro in_html(elements, suboption_key='suboptions', parameter_html_prefix='', parameter_rst_prefix='', role_entrypoint=None) %}
+{% macro in_html(elements, suboption_key='suboptions', parameter_html_prefix='', role_entrypoint=None) %}
 .. raw:: html
 
   <table style="width: 100%;">

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

@@ -48,7 +48,7 @@ To check whether it is installed, run ``ansible-galaxy collection list``.
 To install it, use: @{ collection | collection_install | rst_code }@.
 {%   if doc['requirements'] %}
 You need further requirements to be able to use this {% if plugin_type == 'module' %}module{% else %}@{ plugin_type }@ plugin{% endif %},
-see `Requirements <ansible_collections.@{plugin_name}@_@{plugin_type}@_requirements_>`_ for details.
+see `Requirements <@{ rst_requirements_ref(plugin_name, plugin_type) }@_>`_ for details.
 {%   endif %}
 
 To use it in a playbook, specify: ``@{plugin_name}@``.
@@ -108,7 +108,7 @@ Aliases: @{ ', '.join(doc['aliases'] | sort) }@
 {% endif %}
 
 {% if doc['requirements'] -%}
-.. _ansible_collections.@{plugin_name}@_@{plugin_type}@_requirements:
+.. _@{ rst_requirements_ref(plugin_name, plugin_type) }@:
 
 Requirements
 ------------

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

@@ -93,7 +93,7 @@ The below requirements are needed on the remote host and/or the local controller
 Parameters
 ^^^^^^^^^^
 
-@{     parameters_html(ep_doc['options'] | dictsort, suboption_key='options', parameter_html_prefix=entry_point ~ '--', parameter_rst_prefix=entry_point ~ '__', role_entrypoint=entry_point) }@
+@{     parameters_html(ep_doc['options'] | dictsort, suboption_key='options', parameter_html_prefix=entry_point ~ '--', role_entrypoint=entry_point) }@
 {%   endif %}
 
 {%   if ep_doc['attributes'] %}

src/antsibull_docs/jinja2/environment.py

@@ -13,6 +13,13 @@
 from jinja2 import BaseLoader, Environment, FileSystemLoader, PackageLoader
 
 from ..markup.rstify import rst_code, rst_escape
+from ..rst_labels import (
+    get_attribute_ref,
+    get_option_ref,
+    get_plugin_ref,
+    get_requirements_ref,
+    get_return_value_ref,
+)
 from ..utils.collection_name_transformer import CollectionNameTransformer
 from . import FilenameGenerator, OutputFormat
 from .filters import (
@@ -38,7 +45,7 @@
 
 def reference_plugin_rst(plugin_name: str, plugin_type: str) -> str:
     fqcn = f"{plugin_name}"
-    return f"\\ :ref:`{rst_escape(fqcn)} <ansible_collections.{fqcn}_{plugin_type}>`\\ "
+    return f"\\ :ref:`{rst_escape(fqcn)} <{get_plugin_ref(fqcn, plugin_type)}>`\\ "
 
 
 def reference_plugin_rst_simplified(plugin_name: str, plugin_type: str) -> str:
@@ -139,6 +146,11 @@ def doc_environment(
 
     env.globals["reference_plugin_rst"] = make_reference_plugin_rst(output_format)
     env.globals["referable_envvars"] = referable_envvars
+    env.globals["rst_plugin_ref"] = get_plugin_ref
+    env.globals["rst_requirements_ref"] = get_requirements_ref
+    env.globals["rst_attribute_ref"] = get_attribute_ref
+    env.globals["rst_option_ref"] = get_option_ref
+    env.globals["rst_return_value_ref"] = get_return_value_ref
     env.filters["rst_ify"] = make_rst_ify(output_format)
     env.filters["html_ify"] = html_ify
     env.filters["fmt"] = rst_fmt

src/antsibull_docs/markup/rstify.py

@@ -69,7 +69,7 @@ def plugin_option_like_link(
     ) -> t.Optional[str]:
         if current_plugin:
             ref = massage_rst_label("/".join(name))
-            ep = f"{entrypoint}__" if entrypoint is not None else ""
+            ep = f"{entrypoint}--" if entrypoint is not None else ""
             prefix = "return" if what == "retval" else "parameter"
             return f"{prefix}-{ep}{ref}_"
         return self.plugin_link(plugin)
@@ -83,7 +83,7 @@ def _custom_format_option_like(
     ) -> str:
         plugin = part.plugin
         if url and url.endswith("_"):
-            plugin_text = f" (`link <{url}>`_)"
+            plugin_text = f" (`link <#{url[:-1]}>`_)"
         elif plugin:
             plugin_result = [plugin.type]
             if plugin.type not in ("module", "role", "playbook"):

src/antsibull_docs/rst_labels.py

@@ -0,0 +1,74 @@
+# Author: Felix Fontein <[email protected]>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or
+# https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2023, Ansible Project
+"""
+Label helpers.
+"""
+
+from __future__ import annotations
+
+from antsibull_docs.utils.rst import massage_rst_label
+
+
+def get_plugin_ref(plugin_fqcn: str, plugin_type: str) -> str:
+    return f"ansible_collections.{plugin_fqcn}_{plugin_type}"
+
+
+def get_attribute_ref(
+    plugin_fqcn: str,
+    plugin_type: str,
+    role_entrypoint: str | None,
+    attribute: str,
+) -> str:
+    ref = massage_rst_label(attribute)
+    ep = (
+        f"{role_entrypoint}__"
+        if role_entrypoint is not None and plugin_type == "role"
+        else ""
+    )
+    return f"{get_plugin_ref(plugin_fqcn, plugin_type)}__attribute-{ep}{ref}"
+
+
+def get_option_ref(
+    plugin_fqcn: str,
+    plugin_type: str,
+    role_entrypoint: str | None,
+    option: list[str],
+) -> str:
+    ref = "/".join(massage_rst_label(part) for part in option)
+    ep = (
+        f"{role_entrypoint}__"
+        if role_entrypoint is not None and plugin_type == "role"
+        else ""
+    )
+    return f"{get_plugin_ref(plugin_fqcn, plugin_type)}__parameter-{ep}{ref}"
+
+
+def get_return_value_ref(
+    plugin_fqcn: str,
+    plugin_type: str,
+    role_entrypoint: str | None,
+    return_value: list[str],
+) -> str:
+    ref = "/".join(massage_rst_label(part) for part in return_value)
+    ep = (
+        f"{role_entrypoint}__"
+        if role_entrypoint is not None and plugin_type == "role"
+        else ""
+    )
+    return f"{get_plugin_ref(plugin_fqcn, plugin_type)}__return-{ep}{ref}"
+
+
+def get_requirements_ref(
+    plugin_fqcn: str,
+    plugin_type: str,
+    role_entrypoint: str | None = None,
+) -> str:
+    ep = (
+        f"-{role_entrypoint}"
+        if role_entrypoint is not None and plugin_type == "role"
+        else ""
+    )
+    return f"{get_plugin_ref(plugin_fqcn, plugin_type)}_requirements{ep}"

src/sphinx_antsibull_ext/roles.py

@@ -21,17 +21,17 @@
     parse_plugin_name,
     parse_return_value,
 )
-from antsibull_docs.utils.rst import massage_rst_label
+from antsibull_docs.rst_labels import (
+    get_option_ref,
+    get_plugin_ref,
+    get_return_value_ref,
+)
 
 from .sphinx_helper import extract_explicit_title
 
 logger = logging.getLogger(__name__)
 
 
-def _plugin_ref(plugin_fqcn: str, plugin_type: str) -> str:
-    return f"ansible_collections.{plugin_fqcn}_{plugin_type}"
-
-
 def _create_option_reference(
     plugin_fqcn: str | None,
     plugin_type: str | None,
@@ -40,9 +40,7 @@ def _create_option_reference(
 ) -> str | None:
     if not plugin_fqcn or not plugin_type:
         return None
-    ref = massage_rst_label(option.replace(".", "/"))
-    ep = f"{entrypoint}__" if entrypoint is not None else ""
-    return f"{_plugin_ref(plugin_fqcn, plugin_type)}__parameter-{ep}{ref}"
+    return get_option_ref(plugin_fqcn, plugin_type, entrypoint, option.split("."))
 
 
 def _create_return_value_reference(
@@ -53,9 +51,9 @@ def _create_return_value_reference(
 ) -> str | None:
     if not plugin_fqcn or not plugin_type:
         return None
-    ref = massage_rst_label(return_value.replace(".", "/"))
-    ep = f"{entrypoint}__" if entrypoint is not None else ""
-    return f"{_plugin_ref(plugin_fqcn, plugin_type)}__return-{ep}{ref}"
+    return get_return_value_ref(
+        plugin_fqcn, plugin_type, entrypoint, return_value.split(".")
+    )
 
 
 def _create_ref_or_not(
@@ -277,7 +275,7 @@ def plugin_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
     refnode = addnodes.pending_xref(
         plugin_fqcn, nodes.inline(rawtext, title), **options
     )
-    refnode["reftarget"] = _plugin_ref(plugin_fqcn, plugin_type)
+    refnode["reftarget"] = get_plugin_ref(plugin_fqcn, plugin_type)
 
     return [refnode], []