From 213f955489acf3a59293e340e827a05d8e196949 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 6 May 2023 20:15:51 +0200 Subject: [PATCH 1/2] Refactoring to pass collection metadata through to more places. --- src/antsibull_docs/cli/doc_commands/_build.py | 2 +- src/antsibull_docs/docs_parsing/routing.py | 33 +++++++++++-------- src/antsibull_docs/write_docs/indexes.py | 10 ++++-- 3 files changed, 29 insertions(+), 16 deletions(-) diff --git a/src/antsibull_docs/cli/doc_commands/_build.py b/src/antsibull_docs/cli/doc_commands/_build.py index b208c5a5..a3cda373 100644 --- a/src/antsibull_docs/cli/doc_commands/_build.py +++ b/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)) diff --git a/src/antsibull_docs/docs_parsing/routing.py b/src/antsibull_docs/docs_parsing/routing.py index 3293592b..cd8da0d5 100644 --- a/src/antsibull_docs/docs_parsing/routing.py +++ b/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) diff --git a/src/antsibull_docs/write_docs/indexes.py b/src/antsibull_docs/write_docs/indexes.py index d77157d9..ac6a4e4f 100644 --- a/src/antsibull_docs/write_docs/indexes.py +++ b/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) From 65c766e9268ec8e96f89db67bf269b6583b59b13 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 6 May 2023 20:16:29 +0200 Subject: [PATCH 2/2] Add 'no plugins found' message to plugin index templates. --- src/antsibull_docs/data/docsite/list_of_plugins.rst.j2 | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/antsibull_docs/data/docsite/list_of_plugins.rst.j2 b/src/antsibull_docs/data/docsite/list_of_plugins.rst.j2 index 3fd334af..0baeb83d 100644 --- a/src/antsibull_docs/data/docsite/list_of_plugins.rst.j2 +++ b/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 }@ ` -- @{ 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 %}