Semantic markup: make sure that FQCN/plugin type is passed on to rst_ify/html_ify outside of plugin pages (#105)

* Allow to pass in FQCN/plugin type to rst_ify/html_ify filters.

* Use new options in templates.

* Fix syntax.

Author: felixfontein

src/antsibull_docs/data/docsite/list_of_callback_plugins.rst.j2

@@ -18,7 +18,7 @@ See :ref:`list_of_callback_plugins` for the list of *all* callback plugins.
 @{ '-' * (collection_name | length) }@
 
 {%   for plugin_name, plugin_desc in plugins.items() | sort %}
-* :ref:`@{ collection_name }@.@{ plugin_name }@ <ansible_collections.@{ collection_name }@.@{ plugin_name }@_callback>` -- @{ plugin_desc | rst_ify }@
+* :ref:`@{ collection_name }@.@{ plugin_name }@ <ansible_collections.@{ collection_name }@.@{ plugin_name }@_callback>` -- @{ plugin_desc | rst_ify(plugin_fqcn=collection_name ~ '.' ~ plugin_name, plugin_type='callback') }@
 {%   endfor %}
 
 {% else %}

src/antsibull_docs/data/docsite/list_of_env_variables.rst.j2

@@ -19,7 +19,7 @@ Environment variables used by the ansible-core configuration are documented in :
 .. envvar:: @{ env_var.name }@
 
 {%   for paragraph in env_var.description or [] %}
-    @{ paragraph | replace('\n', '\n    ') | rst_ify | indent(4) }@
+    @{ paragraph | replace('\n', '\n    ') | rst_ify(plugin_fqcn='', plugin_type='') | indent(4) }@
 
 {%   endfor %}
     *Used by:*

src/antsibull_docs/data/docsite/list_of_plugins.rst.j2

@@ -34,7 +34,7 @@ Index of all @{ plugin_type | capitalize }@ Plugins
 @{ '-' * (collection_name | length) }@
 
 {%   for plugin_name, plugin_desc in plugins.items() | sort %}
-* :ref:`@{ collection_name }@.@{ plugin_name }@ <ansible_collections.@{ collection_name }@.@{ plugin_name }@_@{ plugin_type }@>` -- @{ plugin_desc | rst_ify }@
+* :ref:`@{ collection_name }@.@{ plugin_name }@ <ansible_collections.@{ collection_name }@.@{ plugin_name }@_@{ plugin_type }@>` -- @{ plugin_desc | rst_ify(plugin_fqcn=collection_name ~ '.' ~ plugin_name, plugin_type=plugin_type) }@
 {%   endfor %}
 
 {% endfor %}

src/antsibull_docs/data/docsite/plugins_by_collection.rst.j2

@@ -10,7 +10,7 @@
 
 {% macro list_plugins(plugin_type) %}
 {%   for name, desc in plugin_maps[plugin_type].items() | sort %}
-* :ref:`@{ name }@ @{ plugin_type }@ <ansible_collections.@{ collection_name }@.@{ name }@_@{ plugin_type }@>` -- @{ desc | rst_ify | indent(width=2) }@
+* :ref:`@{ name }@ @{ plugin_type }@ <ansible_collections.@{ collection_name }@.@{ name }@_@{ plugin_type }@>` -- @{ desc | rst_ify(plugin_fqcn=collection_name ~ '.' ~ name, plugin_type=plugin_type) | indent(width=2) }@
 {%   endfor %}
 {%   if breadcrumbs %}
 

src/antsibull_docs/jinja2/filters.py

@@ -19,9 +19,12 @@
 _EMAIL_ADDRESS = re.compile(r"(?:<{mail}>|\({mail}\)|{mail})".format(mail=r"[\w.+-]+@[\w.-]+\.\w+"))
 
 
-def extract_plugin_data(context: Context) -> t.Tuple[t.Optional[str], t.Optional[str]]:
-    plugin_fqcn = context.get('plugin_name')
-    plugin_type = context.get('plugin_type')
+def extract_plugin_data(context: Context,
+                        plugin_fqcn: t.Optional[str] = None,
+                        plugin_type: t.Optional[str] = None
+                        ) -> t.Tuple[t.Optional[str], t.Optional[str]]:
+    plugin_fqcn = context.get('plugin_name') if plugin_fqcn is None else plugin_fqcn
+    plugin_type = context.get('plugin_type') if plugin_type is None else plugin_type
     if plugin_fqcn is None or plugin_type is None:
         return None, None
     # if plugin_type == 'role':

src/antsibull_docs/jinja2/htmlify.py

@@ -42,7 +42,9 @@ class _Context:
     plugin_fqcn: t.Optional[str]
     plugin_type: t.Optional[str]
 
-    def __init__(self, j2_context: Context):
+    def __init__(self, j2_context: Context,
+                 plugin_fqcn: t.Optional[str] = None,
+                 plugin_type: t.Optional[str] = None):
         self.j2_context = j2_context
         self.counts = {
             'italic': 0,
@@ -59,7 +61,8 @@ def __init__(self, j2_context: Context):
             'return-value': 0,
             'ruler': 0,
         }
-        self.plugin_fqcn, self.plugin_type = extract_plugin_data(j2_context)
+        self.plugin_fqcn, self.plugin_type = extract_plugin_data(
+            j2_context, plugin_fqcn=plugin_fqcn, plugin_type=plugin_type)
 
 
 # In the following, we make heavy use of escaped whitespace ("\ ") being removed from the output.
@@ -295,12 +298,19 @@ def handle(self, parameters: t.List[str], context: t.Any) -> str:
 
 
 @pass_context
-def html_ify(context: Context, text: str) -> str:
+def html_ify(context: Context, text: str,
+             *,
+             plugin_fqcn: t.Optional[str] = None,
+             plugin_type: t.Optional[str] = None) -> str:
     ''' convert symbols like I(this is in italics) to valid HTML '''
     flog = mlog.fields(func='html_ify')
     flog.fields(text=text).debug('Enter')
 
-    our_context = _Context(context)
+    our_context = _Context(
+        context,
+        plugin_fqcn=plugin_fqcn,
+        plugin_type=plugin_type,
+    )
 
     try:
         text = convert_text(text, _COMMAND_SET, html_escape, our_context)

src/antsibull_docs/jinja2/rstify.py

@@ -70,7 +70,9 @@ class _Context:
     plugin_fqcn: t.Optional[str]
     plugin_type: t.Optional[str]
 
-    def __init__(self, j2_context: Context):
+    def __init__(self, j2_context: Context,
+                 plugin_fqcn: t.Optional[str] = None,
+                 plugin_type: t.Optional[str] = None):
         self.j2_context = j2_context
         self.counts = {
             'italic': 0,
@@ -87,7 +89,8 @@ def __init__(self, j2_context: Context):
             'return-value': 0,
             'ruler': 0,
         }
-        self.plugin_fqcn, self.plugin_type = extract_plugin_data(j2_context)
+        self.plugin_fqcn, self.plugin_type = extract_plugin_data(
+            j2_context, plugin_fqcn=plugin_fqcn, plugin_type=plugin_type)
 
 
 # In the following, we make heavy use of escaped whitespace ("\ ") being removed from the output.
@@ -263,12 +266,19 @@ def handle(self, parameters: t.List[str], context: t.Any) -> str:
 
 
 @pass_context
-def rst_ify(context: Context, text: str) -> str:
+def rst_ify(context: Context, text: str,
+            *,
+            plugin_fqcn: t.Optional[str] = None,
+            plugin_type: t.Optional[str] = None) -> str:
     ''' convert symbols like I(this is in italics) to valid restructured text '''
     flog = mlog.fields(func='rst_ify')
     flog.fields(text=text).debug('Enter')
 
-    our_context = _Context(context)
+    our_context = _Context(
+        context,
+        plugin_fqcn=plugin_fqcn,
+        plugin_type=plugin_type,
+    )
 
     try:
         text = convert_text(text, _COMMAND_SET, rst_escape, our_context)

tests/functional/baseline-default/collections/callback_index_stdout.rst

@@ -11,5 +11,5 @@ See :ref:`list_of_callback_plugins` for the list of *all* callback plugins.
 ns2.col
 -------
 
-* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_callback>` -- Foo output
+* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_callback>` -- Foo output \ :ansopt:`ns2.col.foo#callback:bar`\ 
 

tests/functional/baseline-default/collections/index_become.rst

@@ -9,5 +9,5 @@ Index of all Become Plugins
 ns2.col
 -------
 
-* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_become>` -- Use foo
+* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_become>` -- Use foo \ :ansopt:`ns2.col.foo#become:bar`\ 
 

tests/functional/baseline-default/collections/index_cache.rst

@@ -9,5 +9,5 @@ Index of all Cache Plugins
 ns2.col
 -------
 
-* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_cache>` -- Foo files
+* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_cache>` -- Foo files \ :ansopt:`ns2.col.foo#cache:bar`\