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`\ 
 

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

@@ -17,5 +17,5 @@ Index 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_connection.rst

@@ -9,5 +9,5 @@ Index of all Connection Plugins
 ns2.col
 -------
 
-* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_connection>` -- Foo connection
+* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_connection>` -- Foo connection \ :ansopt:`ns2.col.foo#connection:bar`\ 
 

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

@@ -9,5 +9,5 @@ Index of all Filter Plugins
 ns2.col
 -------
 
-* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_filter>` -- The foo filter
+* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_filter>` -- The foo filter \ :ansopt:`ns2.col.foo#filter:bar`\ 
 

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

@@ -9,5 +9,5 @@ Index of all Inventory Plugins
 ns2.col
 -------
 
-* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_inventory>` -- The foo inventory
+* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_inventory>` -- The foo inventory \ :ansopt:`ns2.col.foo#inventory:bar`\ 
 

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

@@ -9,5 +9,5 @@ Index of all Lookup Plugins
 ns2.col
 -------
 
-* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_lookup>` -- Look up some foo
+* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_lookup>` -- Look up some foo \ :ansopt:`ns2.col.foo#lookup:bar`\ 
 

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

@@ -14,6 +14,6 @@ ns.col2
 ns2.col
 -------
 
-* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_module>` -- Do some foo
+* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_module>` -- Do some foo \ :ansopt:`ns2.col.foo#module:bar`\ 
 * :ref:`ns2.col.foo2 <ansible_collections.ns2.col.foo2_module>` -- Another foo
 

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

@@ -9,5 +9,5 @@ Index of all Shell Plugins
 ns2.col
 -------
 
-* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_shell>` -- Foo shell
+* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_shell>` -- Foo shell \ :ansopt:`ns2.col.foo#shell:bar`\ 
 

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

@@ -9,5 +9,5 @@ Index of all Test Plugins
 ns2.col
 -------
 
-* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_test>` -- Is something a foo
+* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_test>` -- Is something a foo \ :ansopt:`ns2.col.foo#test:bar`\ 
 

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

@@ -9,5 +9,5 @@ Index of all Vars Plugins
 ns2.col
 -------
 
-* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_vars>` -- Load foo
+* :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_vars>` -- Load foo \ :ansopt:`ns2.col.foo#vars:bar`\ 
 

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

@@ -37,8 +37,8 @@
 
 .. Title
 
-ns2.col.foo become -- Use foo
-+++++++++++++++++++++++++++++
+ns2.col.foo become -- Use foo \ :ansopt:`ns2.col.foo#become:bar`\ 
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 .. Collection note
 

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

@@ -37,8 +37,8 @@
 
 .. Title
 
-ns2.col.foo cache -- Foo files
-++++++++++++++++++++++++++++++
+ns2.col.foo cache -- Foo files \ :ansopt:`ns2.col.foo#cache:bar`\ 
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 .. Collection note
 
@@ -144,6 +144,43 @@ Parameters
       - Environment variable: :envvar:`ANSIBLE\_CACHE\_PLUGIN\_CONNECTION`
 
 
+      .. raw:: html
+
+        </div>
+
+  * - .. raw:: html
+
+        <div class="ansible-option-cell">
+        <div class="ansibleOptionAnchor" id="parameter-bar"></div>
+
+      .. _ansible_collections.ns2.col.foo_cache__parameter-bar:
+
+      .. rst-class:: ansible-option-title
+
+      **bar**
+
+      .. raw:: html
+
+        <a class="ansibleOptionLink" href="#parameter-bar" title="Permalink to this option"></a>
+
+      .. rst-class:: ansible-option-type-line
+
+      :ansible-option-type:`string`
+
+
+
+
+      .. raw:: html
+
+        </div>
+
+    - .. raw:: html
+
+        <div class="ansible-option-cell">
+
+      Nothing.
+
+
       .. raw:: html
 
         </div>

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

@@ -37,8 +37,8 @@
 
 .. Title
 
-ns2.col.foo callback -- Foo output
-++++++++++++++++++++++++++++++++++
+ns2.col.foo callback -- Foo output \ :ansopt:`ns2.col.foo#callback:bar`\ 
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 .. Collection note
 
@@ -88,6 +88,57 @@ Synopsis
 
 .. Options
 
+Parameters
+----------
+
+
+.. rst-class:: ansible-option-table
+
+.. list-table::
+  :width: 100%
+  :widths: auto
+  :header-rows: 1
+
+  * - Parameter
+    - Comments
+
+  * - .. raw:: html
+
+        <div class="ansible-option-cell">
+        <div class="ansibleOptionAnchor" id="parameter-bar"></div>
+
+      .. _ansible_collections.ns2.col.foo_callback__parameter-bar:
+
+      .. rst-class:: ansible-option-title
+
+      **bar**
+
+      .. raw:: html
+
+        <a class="ansibleOptionLink" href="#parameter-bar" title="Permalink to this option"></a>
+
+      .. rst-class:: ansible-option-type-line
+
+      :ansible-option-type:`string`
+
+
+
+
+      .. raw:: html
+
+        </div>
+
+    - .. raw:: html
+
+        <div class="ansible-option-cell">
+
+      Nothing.
+
+
+      .. raw:: html
+
+        </div>
+
 
 .. Attributes