Hide private plugins.

Author: felixfontein

Diff for: changelogs/fragments/65-private.yml

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

Diff for: src/antsibull_docs/data/docsite/list_of_plugins.rst.j2

@@ -38,5 +38,5 @@ Index of all @{ plugin_type | capitalize }@ Plugins
 {%   endfor %}
 
 {% else %}
-No {% if plugin_type == 'module' %}module{% elif plugin_type == 'role' %}role{% else %}@{ plugin_type }@ plugin{% endif %} found.
+No public {% if plugin_type == 'module' %}module{% elif plugin_type == 'role' %}role{% else %}@{ plugin_type }@ plugin{% endif %} found.
 {% endfor %}

Diff for: 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
 
@@ -81,6 +82,7 @@ class AnsibleCollectionMetadata:
     path: str
     version: str | None
     requires_ansible: str | None
+    private_plugins: Mapping[str, list[str]]  # mapping plugin_type to FQCNs
     docs_config: CollectionConfig
 
     def __init__(
@@ -89,10 +91,12 @@ def __init__(
         docs_config: CollectionConfig,
         version: 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 {}
         self.docs_config = docs_config
 
     def __repr__(self):

Diff for: src/antsibull_docs/docs_parsing/routing.py

@@ -264,18 +264,24 @@ 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

Diff for: src/antsibull_docs/write_docs/collections.py

@@ -98,11 +98,22 @@ async def write_plugin_lists(
                 "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,

Diff for: src/antsibull_docs/write_docs/indexes.py

@@ -59,7 +59,6 @@ async def write_callback_type_index(
 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,
@@ -77,11 +76,22 @@ async def write_plugin_type_index(
     :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,
     )
 

Diff for: 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)",

Diff for: 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)",