Consider plugins whose last component of FQCN starts with '_' as priv…

…ate.

changelogs/fragments/56-private.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "From now on plugins outside ``ansible.builtin`` whose last FQCN component starts with ``_`` are treated as private and marked as such in their documentation, and are no longer listed in plugin indexes (https://github.com/ansible-community/antsibull-docs/pull/56)."

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

@@ -139,6 +139,15 @@ DEPRECATED
 :Alternative: @{ doc['deprecated']['alternative'] | rst_ify }@
 {% endif %}
 
+{% if is_private -%}
+PRIVATE
+-------
+The collection considers this {% if plugin_type == 'module' %}module{% else %}@{ plugin_type }@ plugin{% endif %} private.
+You can use it with the above FQCN, but be warned that @{ collection }@ might not consider
+this {% if plugin_type == 'module' %}module{% else %}@{ plugin_type }@ plugin{% endif %} as part of its public API and
+can make breaking changes even in bugfix releases.
+{% endif %}
+
 Synopsis
 --------
 

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

@@ -112,6 +112,13 @@ DEPRECATED
 :Alternative: @{ ep_doc['deprecated']['alternative'] | rst_ify }@
 {%   endif %}
 
+{% if is_private -%}
+PRIVATE
+-------
+The collection considers this role private. You can use it with the above FQCN, but be warned that @{ collection }@ might
+not consider this role as part of its public API and can make breaking changes even in bugfix releases.
+{% endif %}
+
 Synopsis
 ^^^^^^^^
 

src/antsibull_docs/write_docs.py

@@ -46,6 +46,19 @@ def _render_template(_template: Template, _name: str, **kwargs) -> str:
         raise Exception(f"Error while rendering {_name}") from exc
 
 
+def is_private_plugin(fqcn: str) -> bool:
+    """
+    Return whether the plugin identified by the given FQCN is private.
+
+    Plugins whose last component of the FQCN starts with '_' and which are not part
+    of ansible.builtin are private.
+    """
+    if fqcn.startswith('ansible.builtin.'):
+        return False
+    parts = fqcn.split('.')
+    return parts[-1].startswith('_')
+
+
 def follow_relative_links(path: str) -> str:
     """
     Resolve relative links for path.
@@ -189,6 +202,7 @@ def create_plugin_rst(collection_name: str,
             collection_communication=collection_links.communication,
             collection_issue_tracker=collection_links.issue_tracker,
             for_official_docsite=for_official_docsite,
+            is_private=is_private_plugin(plugin_name),
         )
     else:
         if log_errors and nonfatal_errors:
@@ -213,6 +227,7 @@ def create_plugin_rst(collection_name: str,
                 collection_communication=collection_links.communication,
                 collection_issue_tracker=collection_links.issue_tracker,
                 for_official_docsite=for_official_docsite,
+                is_private=is_private_plugin(plugin_name),
             )
         else:
             plugin_contents = _render_template(
@@ -232,6 +247,7 @@ def create_plugin_rst(collection_name: str,
                 collection_communication=collection_links.communication,
                 collection_issue_tracker=collection_links.issue_tracker,
                 for_official_docsite=for_official_docsite,
+                is_private=is_private_plugin(plugin_name),
             )
 
     flog.debug('Leave')
@@ -624,6 +640,25 @@ def _parse_required_ansible(requires_ansible: str) -> t.List[str]:
     return result
 
 
+def remove_private_plugins(plugin_maps: t.Mapping[str, t.Mapping[str, str]]
+                           ) -> t.Mapping[str, t.Mapping[str, str]]:
+    """
+    Remove all private plugins, and remove all categories with empty plugin list.
+
+    :arg plugin_maps: Mapping of category_type to Mapping of plugin_name to short_description.
+    """
+    result = {}
+    for category_type, category_plugins in plugin_maps.items():
+        result_plugins = {}
+        for plugin, value in category_plugins.items():
+            if is_private_plugin(plugin):
+                continue
+            result_plugins[plugin] = value
+        if result_plugins:
+            result[category_type] = result_plugins
+    return result
+
+
 async def write_plugin_lists(collection_name: str,
                              plugin_maps: t.Mapping[str, t.Mapping[str, str]],
                              template: Template,
@@ -667,6 +702,7 @@ async def write_plugin_lists(collection_name: str,
                 'Cannot parse required_ansible specifier set for {collection_name}',
                 collection_name=collection_name,
             )
+    plugin_maps = remove_private_plugins(plugin_maps)
     index_contents = _render_template(
         template,
         dest_dir,
@@ -818,11 +854,13 @@ async def output_plugin_indexes(plugin_info: PluginCollectionInfoT,
     lib_ctx = app_context.lib_ctx.get()
     async with asyncio_pool.AioPool(size=lib_ctx.thread_max) as pool:
         for plugin_type, per_collection_data in plugin_info.items():
-            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)))
+            per_collection_data = remove_private_plugins(per_collection_data)
+            if per_collection_data:
+                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)))
 
         await asyncio.gather(*writers)
 

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

@@ -0,0 +1,260 @@
+
+.. Document meta
+
+:orphan:
+:github_url: https://github.com/ansible-community/antsibull-docs/edit/main/tests/functional/collections/ansible_collections/ns2/col/plugins/lookup/_bar.py?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr
+
+.. |antsibull-internal-nbsp| unicode:: 0xA0
+    :trim:
+
+.. role:: ansible-attribute-support-label
+.. role:: ansible-attribute-support-property
+.. role:: ansible-attribute-support-full
+.. role:: ansible-attribute-support-partial
+.. role:: ansible-attribute-support-none
+.. role:: ansible-attribute-support-na
+.. role:: ansible-option-type
+.. role:: ansible-option-elements
+.. role:: ansible-option-required
+.. role:: ansible-option-versionadded
+.. role:: ansible-option-aliases
+.. role:: ansible-option-choices
+.. role:: ansible-option-choices-default-mark
+.. role:: ansible-option-default-bold
+.. role:: ansible-option-configuration
+.. role:: ansible-option-returned-bold
+.. role:: ansible-option-sample-bold
+
+.. Anchors
+
+.. _ansible_collections.ns2.col._bar_lookup:
+
+.. Anchors: short name for ansible.builtin
+
+.. Anchors: aliases
+
+
+
+.. Title
+
+ns2.col._bar lookup -- Look up some bar
++++++++++++++++++++++++++++++++++++++++
+
+.. Collection note
+
+.. note::
+    This lookup plugin is part of the `ns2.col collection <https://galaxy.ansible.com/ns2/col>`_ (version 2.1.0).
+
+    To install it, use: :code:`ansible-galaxy collection install ns2.col`.
+
+    To use it in a playbook, specify: :code:`ns2.col._bar`.
+
+.. version_added
+
+.. rst-class:: ansible-version-added
+
+New in ns2.col 1.0.0
+
+.. contents::
+   :local:
+   :depth: 1
+
+.. Deprecated
+
+
+PRIVATE
+-------
+The collection considers this lookup plugin private.
+You can use it with the above FQCN, but be warned that ns2.col might not consider
+this lookup plugin as part of its public API and
+can make breaking changes even in bugfix releases.
+
+Synopsis
+--------
+
+.. Description
+
+- This one is private.
+
+
+.. Aliases
+
+
+.. Requirements
+
+
+
+
+.. Terms
+
+Terms
+-----
+
+.. 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-_terms"></div>
+
+      .. _ansible_collections.ns2.col._bar_lookup__parameter-_terms:
+
+      .. rst-class:: ansible-option-title
+
+      **Terms**
+
+      .. raw:: html
+
+        <a class="ansibleOptionLink" href="#parameter-_terms" title="Permalink to this option"></a>
+
+      .. rst-class:: ansible-option-type-line
+
+      :ansible-option-type:`list` / :ansible-option-elements:`elements=dictionary` / :ansible-option-required:`required`
+
+
+
+
+      .. raw:: html
+
+        </div>
+
+    - .. raw:: html
+
+        <div class="ansible-option-cell">
+
+      Something
+
+
+      .. raw:: html
+
+        </div>
+
+
+
+
+
+.. Options
+
+
+.. Attributes
+
+
+.. Notes
+
+
+.. Seealso
+
+
+.. Examples
+
+Examples
+--------
+
+.. code-block:: yaml+jinja
+
+
+    - name: Look up!
+      ansible.builtin.debug:
+        msg: "{{ lookup('ns2.col._bar', {}) }}"
+
+
+
+
+.. Facts
+
+
+.. Return values
+
+Return Value
+------------
+
+.. rst-class:: ansible-option-table
+
+.. list-table::
+  :width: 100%
+  :widths: auto
+  :header-rows: 1
+
+  * - Key
+    - Description
+
+  * - .. raw:: html
+
+        <div class="ansible-option-cell">
+        <div class="ansibleOptionAnchor" id="return-_raw"></div>
+
+      .. _ansible_collections.ns2.col._bar_lookup__return-_raw:
+
+      .. rst-class:: ansible-option-title
+
+      **Return value**
+
+      .. raw:: html
+
+        <a class="ansibleOptionLink" href="#return-_raw" title="Permalink to this return value"></a>
+
+      .. rst-class:: ansible-option-type-line
+
+      :ansible-option-type:`list` / :ansible-option-elements:`elements=dictionary`
+
+      .. raw:: html
+
+        </div>
+
+    - .. raw:: html
+
+        <div class="ansible-option-cell">
+
+      The resulting stuff.
+
+
+      .. rst-class:: ansible-option-line
+
+      :ansible-option-returned-bold:`Returned:` success
+
+
+      .. raw:: html
+
+        </div>
+
+
+
+..  Status (Presently only deprecated)
+
+
+.. Authors
+
+Authors
+~~~~~~~
+
+- Felix Fontein (@felixfontein)
+
+
+.. hint::
+    Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.
+
+.. Extra links
+
+Collection links
+~~~~~~~~~~~~~~~~
+
+.. raw:: html
+
+  <p class="ansible-links">
+    <a href="https://github.com/ansible-collections/community.general/issues" aria-role="button" target="_blank" rel="noopener external">Issue Tracker</a>
+    <a href="https://github.com/ansible-collections/community.crypto" aria-role="button" target="_blank" rel="noopener external">Homepage</a>
+    <a href="https://github.com/ansible-collections/community.internal_test_tools" aria-role="button" target="_blank" rel="noopener external">Repository (Sources)</a>
+    <a href="https://github.com/ansible-community/antsibull-docs/issues/new?assignees=&amp;labels=&amp;template=bug_report.md" aria-role="button" target="_blank" rel="noopener external">Submit a bug report</a>
+    <a href="./#communication-for-ns2-col" aria-role="button" target="_blank">Communication</a>
+  </p>
+
+.. Parsing errors
+

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

@@ -59,6 +59,7 @@ ns2.col.foo2 module -- Another foo
 .. Deprecated
 
 
+
 Synopsis
 --------