Add custom template parameter

Author: sindrehan

openapidocs/commands/docs.py

@@ -31,7 +31,20 @@
     default="MKDOCS",
     show_default=True,
 )
-def generate_documents_command(source: str, destination: str, style: Union[int, str]):
+@click.option(
+    "-T",
+    "--templates",
+    help=(
+        "Path to a custom templates directory. "
+        "Templates in this directory will override default templates with matching names. "
+        "Unspecified templates will use defaults."
+    ),
+    required=False,
+    default=None,
+)
+def generate_documents_command(
+    source: str, destination: str, style: Union[int, str], templates: Union[str, None]
+):
     """
     Generates other kinds of documents from source OpenAPI Documentation files.
 
@@ -48,7 +61,7 @@ def generate_documents_command(source: str, destination: str, style: Union[int,
     https://github.com/Neoteroi/essentials-openapi
     """
     try:
-        generate_document(source, destination, style)
+        generate_document(source, destination, style, templates)
     except KeyboardInterrupt:  # pragma: nocover
         logger.info("User interrupted")
         exit(1)

openapidocs/mk/generate.py

@@ -1,13 +1,22 @@
+from typing import Optional
+
 from openapidocs.mk.v3 import OpenAPIV3DocumentationHandler
 from openapidocs.utils.source import read_from_source
 
 
-def generate_document(source: str, destination: str, style: int | str):
+def generate_document(
+    source: str,
+    destination: str,
+    style: int | str,
+    templates_path: Optional[str] = None,
+):
     # Note: if support for more kinds of OAD versions will be added, handle a version
     # parameter in this function
 
     data = read_from_source(source)
-    handler = OpenAPIV3DocumentationHandler(data, style=style, source=source)
+    handler = OpenAPIV3DocumentationHandler(
+        data, style=style, source=source, templates_path=templates_path
+    )
 
     html = handler.write()
 

openapidocs/mk/jinja.py

@@ -1,10 +1,20 @@
 """
 This module provides a Jinja2 environment.
 """
+
 import os
 from enum import Enum
-
-from jinja2 import Environment, PackageLoader, Template, select_autoescape
+from pathlib import Path
+from typing import Optional
+
+from jinja2 import (
+    ChoiceLoader,
+    Environment,
+    FileSystemLoader,
+    PackageLoader,
+    Template,
+    select_autoescape,
+)
 
 from . import get_http_status_phrase, highlight_params, read_dict, sort_dict
 from .common import DocumentsWriter, is_reference
@@ -62,29 +72,50 @@ def __init__(
 
 
 def get_environment(
-    package_name: str, views_style: OutputStyle = OutputStyle.MKDOCS
+    package_name: str,
+    views_style: OutputStyle = OutputStyle.MKDOCS,
+    custom_templates_path: Optional[str] = None,
 ) -> Environment:
     templates_folder = f"views_{views_style.name}".lower()
 
+    loaders = []
+
+    # If custom templates path is provided, validate and add FileSystemLoader first
+    if custom_templates_path:
+        custom_path = Path(custom_templates_path)
+        if not custom_path.exists():
+            raise ValueError(
+                f"Custom templates path does not exist: {custom_templates_path}"
+            )
+        if not custom_path.is_dir():
+            raise ValueError(
+                f"Custom templates path is not a directory: {custom_templates_path}"
+            )
+        loaders.append(FileSystemLoader(str(custom_path)))
+
+    # Always add the package loader as fallback
     try:
-        loader = PackageLoader(package_name, templates_folder)
+        loaders.append(PackageLoader(package_name, templates_folder))
     except ValueError as package_loading_error:  # pragma: no cover
-        raise PackageLoadingError(
-            views_style, templates_folder
-        ) from package_loading_error
-    else:
-        env = Environment(
-            loader=loader,
-            autoescape=select_autoescape(["html", "xml"])
-            if os.environ.get("SELECT_AUTOESCAPE") in {"YES", "Y", "1"}
-            else False,
-            auto_reload=True,
-            enable_async=False,
-        )
-        configure_filters(env)
-        configure_functions(env)
+        if not custom_templates_path:
+            raise PackageLoadingError(
+                views_style, templates_folder
+            ) from package_loading_error
+
+    loader = ChoiceLoader(loaders)
+
+    env = Environment(
+        loader=loader,
+        autoescape=select_autoescape(["html", "xml"])
+        if os.environ.get("SELECT_AUTOESCAPE") in {"YES", "Y", "1"}
+        else False,
+        auto_reload=True,
+        enable_async=False,
+    )
+    configure_filters(env)
+    configure_functions(env)
 
-        return env
+    return env
 
 
 class Jinja2DocumentsWriter(DocumentsWriter):
@@ -97,8 +128,9 @@ def __init__(
         self,
         package_name: str,
         views_style: OutputStyle = OutputStyle.MKDOCS,
+        custom_templates_path: Optional[str] = None,
     ) -> None:
-        self._env = get_environment(package_name, views_style)
+        self._env = get_environment(package_name, views_style, custom_templates_path)
 
     @property
     def env(self) -> Environment:

openapidocs/mk/v3/__init__.py

@@ -1,6 +1,7 @@
 """
 This module provides functions to generate Markdown for OpenAPI Version 3.
 """
+
 import copy
 import os
 import warnings
@@ -95,11 +96,14 @@ def __init__(
         writer: Optional[DocumentsWriter] = None,
         style: Union[int, str] = 1,
         source: str = "",
+        templates_path: Optional[str] = None,
     ) -> None:
         self._source = source
         self.texts = texts or EnglishTexts()
         self._writer = writer or Jinja2DocumentsWriter(
-            __name__, views_style=style_from_value(style)
+            __name__,
+            views_style=style_from_value(style),
+            custom_templates_path=templates_path,
         )
         self.doc = self.normalize_data(copy.deepcopy(doc))