Pass collection metadata to more places, and improve plugin index templates (#144)

* Refactoring to pass collection metadata through to more places.

* Add 'no plugins found' message to plugin index templates.

Author: felixfontein

src/antsibull_docs/cli/doc_commands/_build.py

@@ -170,7 +170,7 @@ def generate_docs_for_all_collections(venv: VenvRunner | FakeVenvRunner,
                                                         breadcrumbs=breadcrumbs,
                                                         for_official_docsite=for_official_docsite))
         flog.notice('Finished writing collection namespace index')
-        asyncio.run(output_plugin_indexes(plugin_contents, dest_dir,
+        asyncio.run(output_plugin_indexes(plugin_contents, collection_metadata, dest_dir,
                                           collection_url=collection_url,
                                           collection_install=collection_install,
                                           for_official_docsite=for_official_docsite))

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

@@ -37,4 +37,6 @@ Index of all @{ plugin_type | capitalize }@ Plugins
 * :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 %}
 
+{% else %}
+No {% if plugin_type == 'module' %}module{% elif plugin_type == 'role' %}role{% else %}@{ plugin_type }@ plugin{% endif %} found.
 {% endfor %}

src/antsibull_docs/docs_parsing/routing.py

@@ -215,6 +215,25 @@ def load_meta_runtime(collection_name: str,
     return meta_runtime
 
 
+def _add_symlink_redirects(collection_name: str,
+                           collection_metadata: AnsibleCollectionMetadata,
+                           plugin_routing_out: dict[str, dict[str, dict[str, t.Any]]]
+                           ) -> None:
+    for plugin_type in DOCUMENTABLE_PLUGINS:
+        directory_name = 'modules' if plugin_type == 'module' else plugin_type
+        directory_path = os.path.join(collection_metadata.path, 'plugins', directory_name)
+        plugin_type_routing = plugin_routing_out[plugin_type]
+
+        symlink_redirects = find_symlink_redirects(collection_name, plugin_type, directory_path)
+        for redirect_name, redirect_dst in symlink_redirects.items():
+            if redirect_name not in plugin_type_routing:
+                plugin_type_routing[redirect_name] = {}
+            if 'redirect' not in plugin_type_routing[redirect_name]:
+                plugin_type_routing[redirect_name]['redirect'] = redirect_dst
+            if plugin_type_routing[redirect_name]['redirect'] == redirect_dst:
+                plugin_type_routing[redirect_name]['redirect_is_symlink'] = True
+
+
 async def load_collection_routing(collection_name: str,
                                   collection_metadata: AnsibleCollectionMetadata
                                   ) -> dict[str, dict[str, dict[str, t.Any]]]:
@@ -237,19 +256,7 @@ async def load_collection_routing(collection_name: str,
         # (or need) to handle
         return plugin_routing_out
 
-    for plugin_type in DOCUMENTABLE_PLUGINS:
-        directory_name = 'modules' if plugin_type == 'module' else plugin_type
-        directory_path = os.path.join(collection_metadata.path, 'plugins', directory_name)
-        plugin_type_routing = plugin_routing_out[plugin_type]
-
-        symlink_redirects = find_symlink_redirects(collection_name, plugin_type, directory_path)
-        for redirect_name, redirect_dst in symlink_redirects.items():
-            if redirect_name not in plugin_type_routing:
-                plugin_type_routing[redirect_name] = {}
-            if 'redirect' not in plugin_type_routing[redirect_name]:
-                plugin_type_routing[redirect_name]['redirect'] = redirect_dst
-            if plugin_type_routing[redirect_name]['redirect'] == redirect_dst:
-                plugin_type_routing[redirect_name]['redirect_is_symlink'] = True
+    _add_symlink_redirects(collection_name, collection_metadata, plugin_routing_out)
 
     if collection_name in COLLECTIONS_WITH_FLATMAPPING:
         remove_flatmapping_artifacts(plugin_routing_out)

src/antsibull_docs/write_docs/indexes.py

@@ -18,6 +18,7 @@
 from antsibull_core.utils.io import write_file
 from jinja2 import Template
 
+from ..docs_parsing import AnsibleCollectionMetadata
 from ..env_variables import EnvironmentVariableInfo
 from ..jinja2.environment import doc_environment
 from ..utils.collection_name_transformer import CollectionNameTransformer
@@ -55,6 +56,8 @@ async def write_callback_type_index(callback_type: str,
 
 async def write_plugin_type_index(plugin_type: str,
                                   per_collection_plugins: Mapping[str, Mapping[str, str]],
+                                  # pylint:disable-next=unused-argument
+                                  collection_metadata: Mapping[str, AnsibleCollectionMetadata],
                                   template: Template,
                                   dest_filename: str,
                                   for_official_docsite: bool = False) -> None:
@@ -64,6 +67,7 @@ async def write_plugin_type_index(plugin_type: str,
     :arg plugin_type: The plugin type to write the index for.
     :arg per_collection_plugins: Mapping of collection_name to Mapping of plugin_name to
         short_description.
+    :arg collection_metadata: Dictionary mapping collection names to collection metadata objects.
     :arg template: A template to render the plugin index.
     :arg dest_filename: The destination filename.
     :kwarg for_official_docsite: Default False.  Set to True to use wording specific for the
@@ -128,6 +132,7 @@ async def output_callback_indexes(plugin_info: PluginCollectionInfoT,
 
 
 async def output_plugin_indexes(plugin_info: PluginCollectionInfoT,
+                                collection_metadata: Mapping[str, AnsibleCollectionMetadata],
                                 dest_dir: str,
                                 collection_url: CollectionNameTransformer,
                                 collection_install: CollectionNameTransformer,
@@ -137,6 +142,7 @@ async def output_plugin_indexes(plugin_info: PluginCollectionInfoT,
 
     :arg plugin_info: Mapping of plugin_type to Mapping of collection_name to Mapping of
         plugin_name to short_description.
+    :arg collection_metadata: Dictionary mapping collection names to collection metadata objects.
     :arg dest_dir: The directory to place the documentation in.
     :kwarg for_official_docsite: Default False.  Set to True to use wording specific for the
         official docsite on docs.ansible.com.
@@ -165,8 +171,8 @@ async def output_plugin_indexes(plugin_info: PluginCollectionInfoT,
             filename = os.path.join(collection_toplevel, f'index_{plugin_type}.rst')
             writers.append(await pool.spawn(
                 write_plugin_type_index(
-                    plugin_type, per_collection_data, plugin_list_tmpl, filename,
-                    for_official_docsite=for_official_docsite)))
+                    plugin_type, per_collection_data, collection_metadata, plugin_list_tmpl,
+                    filename, for_official_docsite=for_official_docsite)))
 
         await asyncio.gather(*writers)