Hide private plugins.

Author: felixfontein

changelogs/fragments/65-private.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "Supports hiding private plugins (https://github.com/ansible-community/antsibull-docs/pull/65)."

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 public {% if plugin_type == 'module' %}module{% elif plugin_type == 'role' %}role{% else %}@{ plugin_type }@ plugin{% endif %} found.
 {% endfor %}

src/antsibull_docs/docs_parsing/__init__.py

@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 import os
+from collections.abc import Mapping
 
 from antsibull_core.venv import FakeVenvRunner, VenvRunner
 
@@ -75,14 +76,17 @@ class AnsibleCollectionMetadata:
     path: str
     version: str | None
     requires_ansible: str | None
+    private_plugins: Mapping[str, list[str]]  # mapping plugin_type to FQCNs
 
     def __init__(self,
                  path: str,
                  version: str | None = None,
-                 requires_ansible: str | None = None):
+                 requires_ansible: str | None = None,
+                 private_plugins: Mapping[str, list[str]] | None = None):
         self.path = path
         self.version = version
         self.requires_ansible = requires_ansible
+        self.private_plugins = private_plugins or {}
 
     def __repr__(self):
         return f'AnsibleCollectionMetadata({repr(self.path)}, {repr(self.version)})'

src/antsibull_docs/docs_parsing/routing.py

@@ -215,41 +215,54 @@ 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]]]:
     """
-    Load plugin routing for a collection.
+    Load plugin routing for a collection, and populate the private plugins lists
+    in collection metadata.
     """
     meta_runtime = load_meta_runtime(collection_name, collection_metadata)
     plugin_routing_out: dict[str, dict[str, dict[str, t.Any]]] = {}
     plugin_routing_in = meta_runtime.get('plugin_routing') or {}
+    private_plugins: dict[str, list[str]] = {}
+    collection_metadata.private_plugins = private_plugins
     for plugin_type in DOCUMENTABLE_PLUGINS:
         plugin_type_id = 'modules' if plugin_type == 'module' else plugin_type
         plugin_type_routing = plugin_routing_in.get(plugin_type_id) or {}
-        plugin_routing_out[plugin_type] = {
-            f'{collection_name}.{plugin_name}': process_dates(plugin_record)
-            for plugin_name, plugin_record in plugin_type_routing.items()
-        }
+        plugin_routing_out[plugin_type] = {}
+        private_plugins[plugin_type] = []
+        for plugin_name, plugin_record in plugin_type_routing.items():
+            fqcn = f'{collection_name}.{plugin_name}'
+            plugin_routing_out[plugin_type][fqcn] = process_dates(plugin_record)
+            if plugin_record.get('private', False):
+                private_plugins[plugin_type].append(plugin_name)
 
     if collection_name == 'ansible.builtin':
         # ansible-core has a special directory structure we currently do not want
         # (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/collections.py

@@ -94,11 +94,22 @@ async def write_plugin_lists(collection_name: str,
                 'Cannot parse required_ansible specifier set for {collection_name}',
                 collection_name=collection_name,
             )
+
+    public_plugin_maps: dict[str, Mapping[str, str]] = {}
+    for plugin_type, plugin_data in plugin_maps.items():
+        private_plugins = collection_meta.private_plugins.get(plugin_type) or []
+        public_plugin_data = {}
+        for plugin_name, plugin_info in plugin_data.items():
+            if plugin_name not in private_plugins:
+                public_plugin_data[plugin_name] = plugin_info
+        if public_plugin_data:
+            public_plugin_maps[plugin_type] = public_plugin_data
+
     index_contents = _render_template(
         template,
         dest_dir,
         collection_name=collection_name,
-        plugin_maps=plugin_maps,
+        plugin_maps=public_plugin_maps,
         collection_version=collection_meta.version,
         requires_ansible=requires_ansible,
         link_data=link_data,

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,7 @@ 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]],
+                                  collection_metadata: Mapping[str, AnsibleCollectionMetadata],
                                   template: Template,
                                   dest_filename: str,
                                   for_official_docsite: bool = False) -> None:
@@ -64,16 +66,28 @@ 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
         official docsite on docs.ansible.com.
     """
+    public_per_collection_plugins = {}
+    for collection_name, plugins in per_collection_plugins.items():
+        public_plugins = {}
+        collection_meta = collection_metadata[collection_name]
+        private_plugins = collection_meta.private_plugins.get(plugin_type) or []
+        for plugin_name, plugin_data in plugins.items():
+            if plugin_name not in private_plugins:
+                public_plugins[plugin_name] = plugin_data
+        if public_plugins:
+            public_per_collection_plugins[collection_name] = public_plugins
+
     index_contents = _render_template(
         template,
         dest_filename,
         plugin_type=plugin_type,
-        per_collection_plugins=per_collection_plugins,
+        per_collection_plugins=public_per_collection_plugins,
         for_official_docsite=for_official_docsite,
     )
 
@@ -128,6 +142,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 +152,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 +181,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)
 

tests/functional/ansible-doc-cache-all.json

@@ -1008,6 +1008,39 @@
    }
   },
   "lookup": {
+   "ns2.col.bar": {
+    "doc": {
+     "author": "Felix Fontein (@felixfontein)",
+     "collection": "ns2.col",
+     "description": [
+      "This one is private."
+     ],
+     "filename": "ansible_collections/ns2/col/plugins/lookup/bar.py",
+     "name": "bar",
+     "options": {
+      "_terms": {
+       "description": "Something",
+       "elements": "dict",
+       "required": true,
+       "type": "list"
+      }
+     },
+     "short_description": "Look up some bar",
+     "version_added": "1.0.0",
+     "version_added_collection": "ns2.col"
+    },
+    "examples": "\n- name: Look up!\n  ansible.builtin.debug:\n    msg: \"{{ lookup('ns2.col.bar', {}) }}\"\n",
+    "metadata": null,
+    "return": {
+     "_raw": {
+      "description": [
+       "The resulting stuff."
+      ],
+      "elements": "dict",
+      "type": "list"
+     }
+    }
+   },
    "ns2.col.foo": {
     "doc": {
      "author": "Felix Fontein (@felixfontein)",

tests/functional/ansible-doc-cache-ns2.col.json

@@ -1008,6 +1008,39 @@
    }
   },
   "lookup": {
+   "ns2.col.bar": {
+    "doc": {
+     "author": "Felix Fontein (@felixfontein)",
+     "collection": "ns2.col",
+     "description": [
+      "This one is private."
+     ],
+     "filename": "ansible_collections/ns2/col/plugins/lookup/bar.py",
+     "name": "bar",
+     "options": {
+      "_terms": {
+       "description": "Something",
+       "elements": "dict",
+       "required": true,
+       "type": "list"
+      }
+     },
+     "short_description": "Look up some bar",
+     "version_added": "1.0.0",
+     "version_added_collection": "ns2.col"
+    },
+    "examples": "\n- name: Look up!\n  ansible.builtin.debug:\n    msg: \"{{ lookup('ns2.col.bar', {}) }}\"\n",
+    "metadata": null,
+    "return": {
+     "_raw": {
+      "description": [
+       "The resulting stuff."
+      ],
+      "elements": "dict",
+      "type": "list"
+     }
+    }
+   },
    "ns2.col.foo": {
     "doc": {
      "author": "Felix Fontein (@felixfontein)",

tests/functional/ansible-version.output

@@ -1,4 +1,4 @@
-ansible [core 2.15.0b1.post0] (stable-2.15 8f0ddcba2c) last updated 2023/04/06 20:47:29 (GMT +200)
+ansible [core 2.16.0.dev0] (devel 88a380c8f0) last updated 2023/04/06 20:47:05 (GMT +200)
   config file = None
   configured module search path = ['<<<<<HOME>>>>>/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
   ansible python module location = <<<<<ANSIBLE>>>>>