Skip to content

Allow to mark plugins as private with runtime metadata #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Allow to mark plugins as private with runtime metadata #65

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions changelogs/fragments/65-private.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
minor_changes:
- "Supports hiding private plugins (https://github.com/ansible-community/antsibull-docs/pull/65)."
2 changes: 1 addition & 1 deletion src/antsibull_docs/data/docsite/ansible-docsite/list_of_plugins.rst.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,5 +41,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 %}
4 changes: 4 additions & 0 deletions src/antsibull_docs/docs_parsing/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
from __future__ import annotations

import os
from collections.abc import Mapping

from antsibull_core.venv import FakeVenvRunner, VenvRunner

Expand Down Expand Up @@ -89,6 +90,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__(
Expand All @@ -97,10 +99,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):
Expand Down
16 changes: 11 additions & 5 deletions src/antsibull_docs/docs_parsing/routing.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -287,18 +287,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
Expand Down
13 changes: 12 additions & 1 deletion src/antsibull_docs/write_docs/collections.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,11 +101,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,
Expand Down
14 changes: 12 additions & 2 deletions src/antsibull_docs/write_docs/indexes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,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,
Expand All @@ -78,11 +77,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,
)

Expand Down
33 changes: 33 additions & 0 deletions tests/functional/ansible-doc-cache-all-others.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8853,6 +8853,39 @@
}
}
},
"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)",
Expand Down
33 changes: 33 additions & 0 deletions tests/functional/ansible-doc-cache-all.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8819,6 +8819,39 @@
}
}
},
"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)",
Expand Down
33 changes: 33 additions & 0 deletions tests/functional/ansible-doc-cache-ansible.builtin-ns.col2-ns2.col.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8819,6 +8819,39 @@
}
}
},
"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)",
Expand Down
33 changes: 33 additions & 0 deletions tests/functional/ansible-doc-cache-ansible.builtin-ns2.col.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8819,6 +8819,39 @@
}
}
},
"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)",
Expand Down
33 changes: 33 additions & 0 deletions tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1030,6 +1030,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)",
Expand Down
33 changes: 33 additions & 0 deletions tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1030,6 +1030,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)",
Expand Down
Loading