Prepare supporting multiple output formats. (#176)

Author: felixfontein

src/antsibull_docs/cli/doc_commands/_build.py

@@ -28,6 +28,7 @@
     load_ansible_config,
 )
 from ...extra_docs import load_collections_extra_docs
+from ...jinja2.environment import OutputFormat
 from ...process_docs import (
     get_callback_plugin_contents,
     get_collection_contents,
@@ -56,6 +57,8 @@ def generate_docs_for_all_collections(
     venv: VenvRunner | FakeVenvRunner,
     collection_dir: str | None,
     dest_dir: str,
+    output_format: OutputFormat,
+    *,
     collection_names: list[str] | None = None,
     create_indexes: bool = True,
     squash_hierarchy: bool = False,
@@ -72,6 +75,7 @@ def generate_docs_for_all_collections(
                          If ``None``, the collections are assumed to be in the current
                          search path for Ansible.
     :arg dest_dir: The directory into which the documentation is written.
+    :arg output_format: The output format.
     :kwarg collection_names: Optional list of collection names. If specified, only documentation
                              for these collections will be collected and generated.
     :kwarg create_indexes: Whether to create the collection, namespace, and plugin indexes. By
@@ -187,6 +191,7 @@ def generate_docs_for_all_collections(
                 dest_dir,
                 collection_url=collection_url,
                 collection_install=collection_install,
+                output_format=output_format,
                 breadcrumbs=breadcrumbs,
                 for_official_docsite=for_official_docsite,
                 referable_envvars=referable_envvars,
@@ -199,6 +204,7 @@ def generate_docs_for_all_collections(
                 dest_dir,
                 collection_url=collection_url,
                 collection_install=collection_install,
+                output_format=output_format,
                 breadcrumbs=breadcrumbs,
                 for_official_docsite=for_official_docsite,
                 referable_envvars=referable_envvars,
@@ -212,6 +218,7 @@ def generate_docs_for_all_collections(
                 dest_dir,
                 collection_url=collection_url,
                 collection_install=collection_install,
+                output_format=output_format,
                 for_official_docsite=for_official_docsite,
                 referable_envvars=referable_envvars,
             )
@@ -223,6 +230,7 @@ def generate_docs_for_all_collections(
                 dest_dir,
                 collection_url=collection_url,
                 collection_install=collection_install,
+                output_format=output_format,
                 for_official_docsite=for_official_docsite,
                 referable_envvars=referable_envvars,
             )
@@ -239,6 +247,7 @@ def generate_docs_for_all_collections(
             squash_hierarchy=squash_hierarchy,
             extra_docs_data=extra_docs_data,
             link_data=link_data,
+            output_format=output_format,
             breadcrumbs=breadcrumbs,
             for_official_docsite=for_official_docsite,
             referable_envvars=referable_envvars,
@@ -254,6 +263,7 @@ def generate_docs_for_all_collections(
             collection_install=collection_install,
             collection_metadata=collection_metadata,
             link_data=link_data,
+            output_format=output_format,
             squash_hierarchy=squash_hierarchy,
             for_official_docsite=for_official_docsite,
             referable_envvars=referable_envvars,
@@ -271,6 +281,7 @@ def generate_docs_for_all_collections(
             collection_install=collection_install,
             collection_metadata=collection_metadata,
             link_data=link_data,
+            output_format=output_format,
             squash_hierarchy=squash_hierarchy,
             use_html_blobs=use_html_blobs,
             for_official_docsite=for_official_docsite,
@@ -288,6 +299,7 @@ def generate_docs_for_all_collections(
         output_environment_variables(
             dest_dir,
             referenced_env_vars,
+            output_format=output_format,
             squash_hierarchy=squash_hierarchy,
             referable_envvars=referable_envvars,
         )

src/antsibull_docs/cli/doc_commands/collection.py

@@ -21,6 +21,7 @@
 from antsibull_core.venv import FakeVenvRunner
 
 from ... import app_context
+from ...jinja2.environment import OutputFormat
 from ._build import generate_docs_for_all_collections
 
 mlog = log.fields(mod=__name__)
@@ -38,7 +39,8 @@ def generate_collection_docs(collection_dir: str | None, squash_hierarchy: bool)
         venv,
         collection_dir,
         app_ctx.extra["dest_dir"],
-        app_ctx.extra["collections"],
+        OutputFormat.ANSIBLE_DOCSITE,
+        collection_names=app_ctx.extra["collections"],
         create_indexes=app_ctx.indexes and not squash_hierarchy,
         squash_hierarchy=squash_hierarchy,
         breadcrumbs=app_ctx.breadcrumbs,

src/antsibull_docs/cli/doc_commands/current.py

@@ -11,6 +11,7 @@
 from antsibull_core.venv import FakeVenvRunner
 
 from ... import app_context
+from ...jinja2.environment import OutputFormat
 from ._build import generate_docs_for_all_collections
 
 mlog = log.fields(mod=__name__)
@@ -37,6 +38,7 @@ def generate_docs() -> int:
         venv,
         app_ctx.extra["collection_dir"],
         app_ctx.extra["dest_dir"],
+        OutputFormat.ANSIBLE_DOCSITE,
         breadcrumbs=app_ctx.breadcrumbs,
         use_html_blobs=app_ctx.use_html_blobs,
         fail_on_error=app_ctx.extra["fail_on_error"],

src/antsibull_docs/cli/doc_commands/devel.py

@@ -22,6 +22,7 @@
 from antsibull_core.venv import FakeVenvRunner, VenvRunner
 
 from ... import app_context
+from ...jinja2.environment import OutputFormat
 from ._build import generate_docs_for_all_collections
 
 mlog = log.fields(mod=__name__)
@@ -173,6 +174,7 @@ def generate_docs() -> int:
             venv,
             collection_dir,
             app_ctx.extra["dest_dir"],
+            OutputFormat.ANSIBLE_DOCSITE,
             breadcrumbs=app_ctx.breadcrumbs,
             use_html_blobs=app_ctx.use_html_blobs,
             fail_on_error=app_ctx.extra["fail_on_error"],

src/antsibull_docs/cli/doc_commands/plugin.py

@@ -26,7 +26,7 @@
 from ...collection_links import CollectionLinks
 from ...docs_parsing import AnsibleCollectionMetadata
 from ...docs_parsing.fqcn import get_fqcn_parts, is_fqcn
-from ...jinja2.environment import doc_environment
+from ...jinja2.environment import OutputFormat, doc_environment
 from ...process_docs import normalize_plugin_info
 from ...utils.collection_name_transformer import CollectionNameTransformer
 from ...write_docs.plugins import write_plugin_rst
@@ -40,6 +40,7 @@ def generate_plugin_docs(
     collection_name: str,
     plugin: str,
     output_path: str,
+    output_format: OutputFormat,
 ) -> int:
     """
     Render documentation for a locally installed plugin.
@@ -114,9 +115,9 @@ def generate_plugin_docs(
         "ansible-galaxy collection install {namespace}.{name}",
     )
     env = doc_environment(
-        ("antsibull_docs.data", "docsite"),
         collection_url=collection_url,
         collection_install=collection_install,
+        output_format=output_format,
     )
     # Get the templates
     plugin_tmpl = env.get_template("plugin.rst.j2")
@@ -179,5 +180,10 @@ def generate_docs() -> int:
     plugin_name = ".".join([namespace, collection, plugin])
 
     return generate_plugin_docs(
-        plugin_type, plugin_name, collection_name, plugin, output_path
+        plugin_type,
+        plugin_name,
+        collection_name,
+        plugin,
+        output_path,
+        OutputFormat.ANSIBLE_DOCSITE,
     )

src/antsibull_docs/cli/doc_commands/stable.py

@@ -23,6 +23,7 @@
 from antsibull_core.venv import FakeVenvRunner, VenvRunner
 
 from ... import app_context
+from ...jinja2.environment import OutputFormat
 from ._build import generate_docs_for_all_collections
 
 mlog = log.fields(mod=__name__)
@@ -175,6 +176,7 @@ def generate_docs() -> int:
             venv,
             collection_dir,
             app_ctx.extra["dest_dir"],
+            OutputFormat.ANSIBLE_DOCSITE,
             breadcrumbs=app_ctx.breadcrumbs,
             use_html_blobs=app_ctx.use_html_blobs,
             fail_on_error=app_ctx.extra["fail_on_error"],

src/antsibull_docs/data/docsite/list_of_callback_plugins.rst.j2 renamed to src/antsibull_docs/data/docsite/ansible-docsite/list_of_callback_plugins.rst.j2

@@ -2,3 +2,35 @@
 # https://www.gnu.org/licenses/gpl-3.0.txt)
 # SPDX-License-Identifier: GPL-3.0-or-later
 # SPDX-FileCopyrightText: 2020, Ansible Project
+"""
+Output format enum.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class OutputFormatObj:
+    def __init__(self, value: str, extension: str):
+        self._value_ = value
+        self._value = value
+        self._extension = extension
+
+    @property
+    def value(self):
+        return self._value
+
+    @property
+    def extension(self):
+        return self._extension
+
+    def __str__(self):
+        return self._value
+
+
+class OutputFormat(OutputFormatObj, Enum):
+    def __new__(cls, value: str, extension: str):
+        return OutputFormatObj(value, extension)
+
+    ANSIBLE_DOCSITE = ("ansible-docsite", ".rst.j2")

src/antsibull_docs/data/docsite/list_of_collections.rst.j2 renamed to src/antsibull_docs/data/docsite/ansible-docsite/list_of_collections.rst.j2

@@ -15,16 +15,17 @@
 
 from ..markup.rstify import rst_code, rst_escape
 from ..utils.collection_name_transformer import CollectionNameTransformer
+from . import OutputFormat
 from .filters import (
     do_max,
     documented_type,
     extract_options_from_list,
     html_ify,
+    make_rst_ify,
     massage_author_name,
     move_first,
     remove_options_from_list,
     rst_fmt,
-    rst_ify,
     rst_xline,
     to_ini_value,
     to_json,
@@ -53,27 +54,56 @@ def reference_plugin_rst(plugin_name: str, plugin_type: str) -> str:
     return f"\\ :ref:`{rst_escape(fqcn)} <ansible_collections.{fqcn}_{plugin_type}>`\\ "
 
 
+def get_template_location(output_format: OutputFormat) -> tuple[str, str]:
+    """
+    Return template location given the output format.
+    """
+    return ("antsibull_docs.data", f"docsite/{output_format.value}")
+
+
+def get_template_filename(filename_base: str, output_format: OutputFormat) -> str:
+    """
+    Return template filename given the filename base and the output format.
+    """
+    return f"{filename_base}{output_format.extension}"
+
+
+def _get_loader(
+    template_location: str | tuple[str, str] | None, output_format: OutputFormat | None
+) -> BaseLoader:
+    if template_location is None:
+        if output_format is None:
+            raise ValueError(
+                "Either template_location or output_format must be provided"
+            )
+        template_location = get_template_location(output_format)
+
+    if isinstance(template_location, str) and os.path.exists(template_location):
+        return FileSystemLoader(template_location)
+
+    if isinstance(template_location, str):
+        template_pkg = template_location
+        template_path = "templates"
+    else:
+        template_pkg = template_location[0]
+        template_path = template_location[1]
+
+    return PackageLoader(template_pkg, template_path)
+
+
 def doc_environment(
-    template_location: str | tuple[str, str],
+    template_location: str | tuple[str, str] | None = None,
     *,
     extra_filters: Mapping[str, t.Callable] | None = None,
     extra_tests: Mapping[str, t.Callable] | None = None,
     collection_url: CollectionNameTransformer | None = None,
     collection_install: CollectionNameTransformer | None = None,
     referable_envvars: set[str] | None = None,
+    output_format: OutputFormat | None = None,
 ) -> Environment:
-    loader: BaseLoader
-    if isinstance(template_location, str) and os.path.exists(template_location):
-        loader = FileSystemLoader(template_location)
-    else:
-        if isinstance(template_location, str):
-            template_pkg = template_location
-            template_path = "templates"
-        else:
-            template_pkg = template_location[0]
-            template_path = template_location[1]
-
-        loader = PackageLoader(template_pkg, template_path)
+    loader = _get_loader(template_location, output_format)
+    if output_format is None:
+        output_format = OutputFormat.ANSIBLE_DOCSITE
 
     env = Environment(
         loader=loader,
@@ -97,7 +127,7 @@ def doc_environment(
 
     env.globals["reference_plugin_rst"] = reference_plugin_rst
     env.globals["referable_envvars"] = referable_envvars
-    env.filters["rst_ify"] = rst_ify
+    env.filters["rst_ify"] = make_rst_ify(output_format)
     env.filters["html_ify"] = html_ify
     env.filters["fmt"] = rst_fmt
     env.filters["rst_code"] = rst_code