Rename docsite -> extra_docs.

antsibull/cli/antsibull_lint.py

@@ -24,7 +24,7 @@
 from antsibull_changelog.logger import setup_logger
 
 from ..args import get_toplevel_parser, normalize_toplevel_options
-from ..lint_docsite_docs import lint_collection_docsite_files
+from ..lint_extra_docs import lint_collection_extra_docs_files
 
 
 def run(args: List[str]) -> int:
@@ -58,8 +58,8 @@ def run(args: List[str]) -> int:
 
         collection_docs = subparsers.add_parser('collection-docs',
                                                 parents=[common],
-                                                help='Collection docs linter for inclusion in'
-                                                     ' docsite')
+                                                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',
@@ -111,7 +111,7 @@ def command_lint_collection_docs(args: Any) -> int:
 
     :arg args: Parsed arguments
     """
-    errors = lint_collection_docsite_files(args.collection_root_path)
+    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])

antsibull/cli/doc_commands/stable.py

@@ -21,7 +21,7 @@
 from ...collections import install_together
 from ...compat import asyncio_run, best_get_loop
 from ...dependency_files import DepsFile
-from ...docsite_docs import load_collections_docsites
+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 (
@@ -40,7 +40,7 @@
     output_collection_namespace_indexes,
     output_indexes,
     output_plugin_indexes,
-    output_docsites,
+    output_extra_docs,
 )
 from ...utils.transformations import get_collection_namespaces
 
@@ -331,9 +331,9 @@ def generate_docs_for_all_collections(venv: t.Union[VenvRunner, FakeVenvRunner],
     flog.debug('Finished loading errors')
     """
 
-    # Load collection docsite data
-    docsite_data = asyncio_run(load_collections_docsites(collection_metadata))
-    flog.debug('Finished getting collection docsite data')
+    # Load collection extra docs data
+    extra_docs_data = asyncio_run(load_collections_extra_docs(collection_metadata))
+    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)
@@ -357,7 +357,7 @@ 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,
-                               docsite_data=docsite_data))
+                               extra_docs_data=extra_docs_data))
     flog.notice('Finished writing indexes')
 
     asyncio_run(output_all_plugin_stub_rst(stubs_info, dest_dir,
@@ -371,9 +371,9 @@ def generate_docs_for_all_collections(venv: t.Union[VenvRunner, FakeVenvRunner],
                                       squash_hierarchy=squash_hierarchy))
     flog.debug('Finished writing plugin docs')
 
-    asyncio_run(output_docsites(dest_dir, docsite_data,
-                                squash_hierarchy=squash_hierarchy))
-    flog.debug('Finished writing extra docsite 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,7 +14,7 @@ Collection version @{ collection_version }@
 .. toctree::
     :maxdepth: 1
 
-{% for section in docsite_sections %}
+{% for section in extra_docs_sections %}
 @{section.title}@
 @{ '-' * (section.title | length) }@
 

antsibull/docsite_docs.py → antsibull/extra_docs.py

@@ -23,7 +23,7 @@
 _RST_LABEL_DEFINITION = re.compile(r'''^\.\. _([^:]+):''')
 
 
-class DocsiteIndexError(Exception):
+class ExtraDocsIndexError(Exception):
     pass
 
 
@@ -37,16 +37,16 @@ def __init__(self, title: str, toctree: t.List[str]):
 
 
 #: A tuple consisting of a list of sections and a list of RST documents as tuples
-#: (relative path in docsite, content).
-CollectionDocsiteInfoT = t.Tuple[t.List[Section], t.List[t.Tuple[str, str]]]
+#: (relative path in docs/docsite/rst, content).
+CollectionExtraDocsInfoT = t.Tuple[t.List[Section], t.List[t.Tuple[str, str]]]
 
 
-def find_docsite_docs(path_to_collection: str) -> t.List[t.Tuple[str, str]]:
-    '''Enumerate all docsite RST files for a collection path.
+def find_extra_docs(path_to_collection: str) -> t.List[t.Tuple[str, str]]:
+    '''Enumerate all extra docs RST files for a collection path.
 
     :arg path_to_collection: Path to a collection.
     :arg collection_name: Dotted collection name.
-    :returns: A list of tuples (absolute path, relative path in docsite)
+    :returns: A list of tuples (absolute path, relative path in docs/docsite/rst)
     '''
     docs_dir = os.path.join(path_to_collection, 'docs', 'docsite', 'rst')
     if not os.path.isdir(docs_dir):
@@ -71,7 +71,7 @@ def get_label_prefix(collection_name: str) -> str:
 
 def lint_required_conditions(content: str, collection_name: str
                              ) -> t.Tuple[t.List[str], t.List[t.Tuple[int, int, str]]]:
-    '''Check a docsite RST file's content for whether it satisfied the required conditions.
+    '''Check a extra docs RST file's content for whether it satisfied the required conditions.
 
     :arg content: Content of a RST document.
     :arg collection_name: Dotted collection name.
@@ -131,18 +131,18 @@ def load_section(yaml_section: t.Dict[str, t.Any], section_index: int = 0
     return Section(yaml_section['title'], toctree), errors
 
 
-def load_docsite_index(index_path: str) -> t.Tuple[t.List[Section], t.List[str]]:
-    '''Load a docsite extra-docs.yml file.
+def load_extra_docs_index(index_path: str) -> t.Tuple[t.List[Section], t.List[str]]:
+    '''Load a collection's extra-docs.yml file.
 
     :arg index_path: Path to extra-docs.yml (does not need to exist).
     :returns: A tuple consisting of a list of sections and a list of error messages.
-    :raises: DocsiteIndexError if extra-docs.yml does not exist
+    :raises: ExtraDocsIndexError if extra-docs.yml does not exist
     '''
     sections: t.List[Section] = []
     errors: t.List[str] = []
 
     if not os.path.isfile(index_path):
-        raise DocsiteIndexError('extra-docs.yml does not exist')
+        raise ExtraDocsIndexError('extra-docs.yml does not exist')
 
     try:
         index = load_yaml_file(index_path)
@@ -161,32 +161,32 @@ def load_docsite_index(index_path: str) -> t.Tuple[t.List[Section], t.List[str]]
     return sections, errors
 
 
-async def load_collection_docsite(collection_name: str,
-                                  collection_metadata: AnsibleCollectionMetadata,
-                                  path_prefix: str = 'docsite/'
-                                  ) -> CollectionDocsiteInfoT:
-    '''Given a collection name and collection metadata, load docsite data.
+async def load_collection_extra_docs(collection_name: str,
+                                     collection_metadata: AnsibleCollectionMetadata,
+                                     path_prefix: str = 'docsite/'
+                                     ) -> CollectionExtraDocsInfoT:
+    '''Given a collection name and collection metadata, load extra docs data.
 
     :arg collection_name: Dotted collection name.
     :arg collection_metadata: Collection metadata object.
     :arg path_prefix: Prefix to add to relative paths, and toctree entries.
     :returns: A tuple consisting of a list of sections and a list of RST documents as tuples
-              (relative path in docsite, content).
+              (relative path in docs/docsite/rst, content).
     '''
-    flog = mlog.fields(func='load_collection_docsite')
+    flog = mlog.fields(func='load_collection_extra_docs')
     flog.debug('Enter')
 
     index_path = os.path.join(collection_metadata.path, 'docs', 'docsite', 'extra-docs.yml')
     try:
-        sections, _ = load_docsite_index(index_path)
-    except DocsiteIndexError:
+        sections, _ = load_extra_docs_index(index_path)
+    except ExtraDocsIndexError:
         sections = []
 
     for section in sections:
         for i, toctree in enumerate(section.toctree):
             section.toctree[i] = path_prefix + toctree
     documents = []
-    for doc in find_docsite_docs(collection_metadata.path):
+    for doc in find_extra_docs(collection_metadata.path):
         try:
             # Load content
             async with aiofiles.open(doc[0], 'r', encoding='utf-8') as f:
@@ -205,14 +205,15 @@ async def load_collection_docsite(collection_name: str,
     return sections, documents
 
 
-async def load_collections_docsites(collection_metadata: t.Mapping[str, AnsibleCollectionMetadata]
-                                    ) -> t.Mapping[str, CollectionDocsiteInfoT]:
-    '''Load docsite data.
+async def load_collections_extra_docs(collection_metadata: t.Mapping[
+                                          str, AnsibleCollectionMetadata]
+                                      ) -> t.Mapping[str, CollectionExtraDocsInfoT]:
+    '''Load extra docs data.
 
     :arg collection_metadata: Mapping of collection_name to AnsibleCollectionMetadata.
-    :returns: A mapping of collection_name to CollectionDocsiteInfoT.
+    :returns: A mapping of collection_name to CollectionExtraDocsInfoT.
     '''
-    flog = mlog.fields(func='load_collections_docsites')
+    flog = mlog.fields(func='load_collections_extra_docs')
     flog.debug('Enter')
 
     loaders = {}
@@ -221,7 +222,7 @@ async def load_collections_docsites(collection_metadata: t.Mapping[str, AnsibleC
     async with asyncio_pool.AioPool(size=lib_ctx.thread_max) as pool:
         for collection_name, metadata in collection_metadata.items():
             loaders[collection_name] = await pool.spawn(
-                load_collection_docsite(collection_name, metadata))
+                load_collection_extra_docs(collection_name, metadata))
 
         responses = await asyncio.gather(*loaders.values())
 

antsibull/lint_docsite_docs.py → antsibull/lint_extra_docs.py

@@ -11,11 +11,11 @@
 import docutils.utils
 import rstcheck
 
-from .docsite_docs import (
-    find_docsite_docs,
+from .extra_docs import (
+    find_extra_docs,
     lint_required_conditions,
-    load_docsite_index,
-    DocsiteIndexError,
+    load_extra_docs_index,
+    ExtraDocsIndexError,
 )
 from .yaml import load_yaml_file
 
@@ -36,7 +36,7 @@ def load_collection_name(path_to_collection: str) -> str:
 
 def lint_optional_conditions(content: str, path: str, collection_name: str
                              ) -> t.List[t.Tuple[int, int, str]]:
-    '''Check a docsite RST file's content for whether it satisfied the required conditions.
+    '''Check a extra docs RST file's content for whether it satisfied the required conditions.
 
     Return a list of errors.
     '''
@@ -46,15 +46,16 @@ def lint_optional_conditions(content: str, path: str, collection_name: str
     return [(result[0], 0, result[1]) for result in results]
 
 
-def lint_collection_docsite_files(path_to_collection: str) -> t.List[t.Tuple[str, int, int, str]]:
+def lint_collection_extra_docs_files(path_to_collection: str
+                                     ) -> t.List[t.Tuple[str, int, int, str]]:
     try:
         collection_name = load_collection_name(path_to_collection)
     except Exception:
         return [(
             path_to_collection, 0, 0, 'Cannot identify collection with galaxy.yml at this path')]
     result = []
     all_labels = set()
-    docs = find_docsite_docs(path_to_collection)
+    docs = find_extra_docs(path_to_collection)
     for doc in docs:
         try:
             # Load content
@@ -71,9 +72,9 @@ def lint_collection_docsite_files(path_to_collection: str) -> t.List[t.Tuple[str
             result.append((doc[0], 0, 0, str(e)))
     index_path = os.path.join(path_to_collection, 'docs', 'docsite', 'extra-docs.yml')
     try:
-        sections, errors = load_docsite_index(index_path)
+        sections, errors = load_extra_docs_index(index_path)
         result.extend((index_path, 0, 0, error) for error in errors)
-    except DocsiteIndexError as exc:
+    except ExtraDocsIndexError as exc:
         if len(docs) > 0:
             # Only report the missing index_path as an error if we found documents
             result.append((index_path, 0, 0, str(exc)))

antsibull/write_docs.py

@@ -16,7 +16,7 @@
 from . import app_context
 from .jinja2.environment import doc_environment
 from .logging import log
-from .docsite_docs import CollectionDocsiteInfoT
+from .extra_docs import CollectionExtraDocsInfoT
 from .docs_parsing import AnsibleCollectionMetadata
 
 
@@ -351,7 +351,7 @@ async def write_plugin_lists(collection_name: str,
                              template: Template,
                              dest_dir: str,
                              collection_meta: AnsibleCollectionMetadata,
-                             docsite_data: CollectionDocsiteInfoT) -> None:
+                             extra_docs_data: CollectionExtraDocsInfoT) -> None:
     """
     Write an index page for each collection.
 
@@ -361,14 +361,14 @@ async def write_plugin_lists(collection_name: str,
     :arg template: A template to render the collection index.
     :arg dest_dir: The destination directory to output the index into.
     :arg collection_meta: Metadata for the collection.
-    :arg docsite_data: Extra docsite data for the collection.
+    :arg extra_docs_data: Extra docs data for the collection.
     """
     index_contents = template.render(
         collection_name=collection_name,
         plugin_maps=plugin_maps,
         collection_version=collection_meta.version,
         add_toctrees=ADD_TOCTREES,
-        docsite_sections=docsite_data[0])
+        extra_docs_sections=extra_docs_data[0])
 
     # This is only safe because we made sure that the top of the directory tree we're writing to
     # (docs/docsite/rst) is only writable by us.
@@ -484,7 +484,7 @@ async def output_plugin_indexes(plugin_info: PluginCollectionInfoT,
 async def output_indexes(collection_to_plugin_info: CollectionInfoT,
                          dest_dir: str,
                          collection_metadata: t.Mapping[str, AnsibleCollectionMetadata],
-                         docsite_data: t.Mapping[str, CollectionDocsiteInfoT],
+                         extra_docs_data: t.Mapping[str, CollectionExtraDocsInfoT],
                          squash_hierarchy: bool = False,
                          ) -> None:
     """
@@ -494,7 +494,7 @@ async def output_indexes(collection_to_plugin_info: CollectionInfoT,
         of plugin_name to short_description.
     :arg dest_dir: The directory to place the documentation in.
     :arg collection_metadata: Dictionary mapping collection names to collection metadata objects.
-    :arg docsite_data: Dictionary mapping collection names to CollectionDocsiteInfoT.
+    :arg extra_docs_data: Dictionary mapping collection names to CollectionExtraDocsInfoT.
     :arg squash_hierarchy: If set to ``True``, no directory hierarchy will be used.
                            Undefined behavior if documentation for multiple collections are
                            created.
@@ -531,26 +531,26 @@ async def output_indexes(collection_to_plugin_info: CollectionInfoT,
             writers.append(await pool.spawn(
                 write_plugin_lists(collection_name, plugin_maps, collection_plugins_tmpl,
                                    collection_dir, collection_metadata[collection_name],
-                                   docsite_data[collection_name])))
+                                   extra_docs_data[collection_name])))
 
         await asyncio.gather(*writers)
 
     flog.debug('Leave')
 
 
-async def output_docsites(dest_dir: str,
-                          docsite_data: t.Mapping[str, CollectionDocsiteInfoT],
-                          squash_hierarchy: bool = False) -> None:
+async def output_extra_docs(dest_dir: str,
+                            extra_docs_data: t.Mapping[str, CollectionExtraDocsInfoT],
+                            squash_hierarchy: bool = False) -> None:
     """
     Generate collection-level index pages for the collections.
 
     :arg dest_dir: The directory to place the documentation in.
-    :arg docsite_data: Dictionary mapping collection names to CollectionDocsiteInfoT.
+    :arg extra_docs_data: Dictionary mapping collection names to CollectionExtraDocsInfoT.
     :arg squash_hierarchy: If set to ``True``, no directory hierarchy will be used.
                            Undefined behavior if documentation for multiple collections are
                            created.
     """
-    flog = mlog.fields(func='output_docsites')
+    flog = mlog.fields(func='output_extra_docs')
     flog.debug('Enter')
 
     writers = []
@@ -562,7 +562,7 @@ async def output_docsites(dest_dir: str,
         collection_toplevel = dest_dir
 
     async with asyncio_pool.AioPool(size=lib_ctx.thread_max) as pool:
-        for collection_name, (_, documents) in docsite_data.items():
+        for collection_name, (_, documents) in extra_docs_data.items():
             if not squash_hierarchy:
                 collection_dir = os.path.join(collection_toplevel, *(collection_name.split('.')))
             else: