Allow collections to have extra documentation next to the generated p…

…lugin docs.

antsibull/build_changelog.py

@@ -247,7 +247,7 @@ def dump_items(builder: RstBuilder, items: PluginDumpT) -> None:
 
 def add_plugins(builder: RstBuilder, data: PluginDataT) -> None:
     plugins: PluginDumpT = []
-    for name, prefix, _, release_entry in data:
+    for name, prefix, dummy, release_entry in data:
         if release_entry:
             for plugin_type, plugin_datas in release_entry.plugins.items():
                 for plugin_data in plugin_datas:
@@ -261,7 +261,7 @@ def add_plugins(builder: RstBuilder, data: PluginDataT) -> None:
 
 def add_objects(builder: RstBuilder, data: PluginDataT) -> None:
     objects: PluginDumpT = []
-    for name, prefix, _, release_entry in data:
+    for name, prefix, dummy, release_entry in data:
         if release_entry:
             for object_type, object_datas in release_entry.objects.items():
                 for object_data in object_datas:
@@ -274,7 +274,7 @@ def add_objects(builder: RstBuilder, data: PluginDataT) -> None:
 
 def add_modules(builder: RstBuilder, data: PluginDataT) -> None:
     modules: PluginDumpT = []
-    for name, prefix, _, release_entry in data:
+    for name, prefix, dummy, release_entry in data:
         if release_entry:
             for module in release_entry.modules:
                 namespace = module.get('namespace') or ''
@@ -351,7 +351,7 @@ def append_changelog(builder: RstBuilder,
     for section, section_title in DEFAULT_SECTIONS:
         maybe_add_section_title = create_title_adder(builder, section_title, 1)
 
-        for name, _, _, release_entry in data:
+        for name, dummy, dummy, release_entry in data:
             if not release_entry or release_entry.has_no_changes([section]):
                 continue
 

antsibull/changelog.py

@@ -240,7 +240,7 @@ async def _get_changelog_file(self, version: PypiVer,
         path = await base_downloader(str(version))
         if os.path.isdir(path):
             changelog: t.Optional[ChangelogData] = None
-            for root, _, files in os.walk(path):
+            for root, dummy, files in os.walk(path):
                 if 'changelog.yaml' in files:
                     with open(os.path.join(root, 'changelog.yaml'), 'rb') as f:
                         changelog = f.read()
@@ -496,7 +496,7 @@ def get_changelog(
     changelog = []
 
     sorted_versions = collect_versions(versions, ansible_changelog.config)
-    for index, (version_str, _) in enumerate(sorted_versions):
+    for index, (version_str, dummy) in enumerate(sorted_versions):
         version, deps = versions[version_str]
         prev_version = None
         if index + 1 < len(sorted_versions):

antsibull/cli/antsibull_lint.py

@@ -24,6 +24,7 @@
 from antsibull_changelog.logger import setup_logger
 
 from ..args import get_toplevel_parser, normalize_toplevel_options
+from ..lint_extra_docs import lint_collection_extra_docs_files
 
 
 def run(args: List[str]) -> int:
@@ -55,6 +56,16 @@ def run(args: List[str]) -> int:
                                     metavar='/path/to/changelog.yaml',
                                     help='path to changelogs/changelog.yaml')
 
+        collection_docs = subparsers.add_parser('collection-docs',
+                                                parents=[common],
+                                                help='Collection extra docs linter for inclusion'
+                                                     ' in docsite')
+        collection_docs.set_defaults(command=command_lint_collection_docs)
+
+        collection_docs.add_argument('collection_root_path',
+                                     metavar='/path/to/collection',
+                                     help='path to collection (directory that includes galaxy.yml)')
+
         if HAS_ARGCOMPLETE:
             argcomplete.autocomplete(parser)
 
@@ -94,6 +105,24 @@ def command_lint_changelog(args: Any) -> int:
     return 3 if messages else 0
 
 
+def command_lint_collection_docs(args: Any) -> int:
+    """
+    Validate docs/docsite/rst/ in a collection.
+
+    :arg args: Parsed arguments
+    """
+    errors = lint_collection_extra_docs_files(args.collection_root_path)
+
+    messages = sorted(set(
+        '%s:%d:%d: %s' % (error[0], error[1], error[2], error[3])
+        for error in errors))
+
+    for message in messages:
+        print(message)
+
+    return 3 if messages else 0
+
+
 def main() -> int:
     """
     Entrypoint called from the script.

antsibull/cli/doc_commands/stable.py

@@ -21,6 +21,7 @@
 from ...collections import install_together
 from ...compat import asyncio_run, best_get_loop
 from ...dependency_files import DepsFile
+from ...extra_docs import load_collections_extra_docs
 from ...docs_parsing.parsing import get_ansible_plugin_info
 from ...docs_parsing.fqcn import get_fqcn_parts
 from ...docs_parsing.routing import (
@@ -39,6 +40,7 @@
     output_collection_namespace_indexes,
     output_indexes,
     output_plugin_indexes,
+    output_extra_docs,
 )
 from ...utils.transformations import get_collection_namespaces
 
@@ -329,8 +331,16 @@ def generate_docs_for_all_collections(venv: t.Union[VenvRunner, FakeVenvRunner],
     flog.debug('Finished loading errors')
     """
 
+    # Load collection extra docs data
+    extra_docs_data = asyncio_run(load_collections_extra_docs(
+        {name: data.path for name, data in collection_metadata.items()}))
+    flog.debug('Finished getting collection extra docs data')
+
     plugin_contents = get_plugin_contents(plugin_info, nonfatal_errors)
     collection_to_plugin_info = get_collection_contents(plugin_contents)
+    # Make sure collections without documentable plugins are mentioned
+    for collection in collection_metadata:
+        collection_to_plugin_info[collection]
     flog.debug('Finished getting collection data')
 
     collection_namespaces = get_collection_namespaces(collection_to_plugin_info.keys())
@@ -347,20 +357,25 @@ def generate_docs_for_all_collections(venv: t.Union[VenvRunner, FakeVenvRunner],
 
     asyncio_run(output_indexes(collection_to_plugin_info, dest_dir,
                                collection_metadata=collection_metadata,
-                               squash_hierarchy=squash_hierarchy))
+                               squash_hierarchy=squash_hierarchy,
+                               extra_docs_data=extra_docs_data))
     flog.notice('Finished writing indexes')
 
     asyncio_run(output_all_plugin_stub_rst(stubs_info, dest_dir,
                                            collection_metadata=collection_metadata,
                                            squash_hierarchy=squash_hierarchy))
-    flog.debug('Finished writing plugin subs')
+    flog.debug('Finished writing plugin stubs')
 
     asyncio_run(output_all_plugin_rst(collection_to_plugin_info, plugin_info,
                                       nonfatal_errors, dest_dir,
                                       collection_metadata=collection_metadata,
                                       squash_hierarchy=squash_hierarchy))
     flog.debug('Finished writing plugin docs')
 
+    asyncio_run(output_extra_docs(dest_dir, extra_docs_data,
+                                  squash_hierarchy=squash_hierarchy))
+    flog.debug('Finished writing extra extra docs docs')
+
 
 def generate_docs() -> int:
     """

antsibull/data/docsite/plugins_by_collection.rst.j2

@@ -14,10 +14,29 @@ Collection version @{ collection_version }@
 .. toctree::
     :maxdepth: 1
 
+{% for section in extra_docs_sections %}
+@{section.title}@
+@{ '-' * (section.title | length) }@
+
+{%   if section.toctree %}
+.. toctree::
+    :maxdepth: 1
+
+{%     for toctree_entry in section.toctree %}
+    @{toctree_entry}@
+{%     endfor %}
+{%   endif %}
+
+{% endfor %}
+
 Plugin Index
 ------------
 
+{% if plugin_maps %}
 These are the plugins in the @{collection_name}@ collection
+{% else %}
+There are no plugins in the @{collection_name}@ collection with automatically generated documentation.
+{% endif %}
 
 {% for category, plugins in plugin_maps.items() | sort %}