apidoc: allow configuring template directories

Author: okarachidera

CHANGES.rst

@@ -68,6 +68,9 @@ Features added
   Patch by Jean-François B.
 * #13508: Initial support for :pep:`695` type aliases.
   Patch by Martin Matouš, Jeremy Maitin-Shepard, and Adam Turner.
+* apidoc: Allow configuring template directories via
+  :confval:`apidoc_template_dir` and the per-module ``template_dir`` option.
+  Patch by Chidera Okara.
 
 Bugs fixed
 ----------

doc/usage/extensions/apidoc.rst

@@ -110,6 +110,11 @@ The apidoc extension uses the following configuration values:
    :code-py:`'automodule_options'`
      See :confval:`apidoc_automodule_options`.
 
+   :code-py:`'template_dir'`
+     A directory containing templates used when generating documentation files.
+     Paths are interpreted relative to the configuration directory when not
+     absolute. See :confval:`apidoc_template_dir`.
+
 .. confval:: apidoc_exclude_patterns
    :type: :code-py:`Sequence[str]`
    :default: :code-py:`()`
@@ -170,3 +175,10 @@ The apidoc extension uses the following configuration values:
    :default: :code-py:`{'members', 'show-inheritance', 'undoc-members'}`
 
    Options to pass to generated :rst:dir:`automodule` directives.
+
+.. confval:: apidoc_template_dir
+   :type: :code-py:`str`
+   :default: :code-py:`None`
+
+   A directory containing templates that override the built-in apidoc templates.
+   Paths are interpreted relative to the configuration directory.

sphinx/ext/apidoc/__init__.py

@@ -11,6 +11,8 @@
 
 from __future__ import annotations
 
+from pathlib import Path
+from types import NoneType
 from typing import TYPE_CHECKING
 
 import sphinx
@@ -54,6 +56,9 @@ def setup(app: Sphinx) -> ExtensionMetadata:
         'env',
         types=frozenset({frozenset, list, set, tuple}),
     )
+    app.add_config_value(
+        'apidoc_template_dir', None, 'env', types=frozenset({NoneType, str, Path})
+    )
     app.add_config_value('apidoc_modules', (), 'env', types=frozenset({list, tuple}))
 
     # Entry point to run apidoc

sphinx/ext/apidoc/_cli.py

@@ -353,4 +353,5 @@ def _full_quickstart(opts: ApidocOptions, /, *, modules: list[str]) -> None:
             d['extensions'].extend(ext.split(','))
 
     if not opts.dry_run:
-        qs.generate(d, silent=True, overwrite=opts.force, templatedir=opts.template_dir)
+        templatedir = str(opts.template_dir) if opts.template_dir is not None else None
+        qs.generate(d, silent=True, overwrite=opts.force, templatedir=templatedir)

sphinx/ext/apidoc/_extension.py

@@ -37,6 +37,7 @@
     'exclude_patterns',
     'automodule_options',
     'max_depth',
+    'template_dir',
 })
 
 
@@ -169,7 +170,24 @@ def _parse_module_options(
         )
     ]
 
-    # TODO template_dir
+    template_dir = _normalize_template_dir(defaults.template_dir, confdir=confdir)
+    if 'template_dir' in options:
+        if options['template_dir'] is None:
+            template_dir = None
+        elif isinstance(options['template_dir'], str):
+            template_dir = _normalize_template_dir(
+                options['template_dir'], confdir=confdir
+            )
+        else:
+            LOGGER.warning(
+                __("apidoc_modules item %i '%s' must be a string"),
+                i,
+                'template_dir',
+                type='apidoc',
+            )
+            template_dir = _normalize_template_dir(
+                defaults.template_dir, confdir=confdir
+            )
 
     max_depth = defaults.max_depth
     if 'max_depth' in options:
@@ -227,6 +245,7 @@ def _parse_module_options(
         implicit_namespaces=bool_options['implicit_namespaces'],
         automodule_options=automodule_options,
         header=module_path.name,
+        template_dir=template_dir,
     )
 
 
@@ -261,3 +280,18 @@ def _check_collection_of_strings(
             )
             return default
     return options[key]
+
+
+def _normalize_template_dir(
+    value: str | Path | None,
+    *,
+    confdir: Path,
+) -> Path | None:
+    """Return a template directory path resolved relative to *confdir*."""
+    if value is None:
+        return None
+
+    path = Path(value)
+    if not path.is_absolute():
+        path = confdir / path
+    return path

sphinx/ext/apidoc/_shared.py

@@ -66,7 +66,7 @@ class ApidocOptions:
     version: str | None = None
     release: str | None = None
     extensions: Sequence[str] | None = None
-    template_dir: str | None = None
+    template_dir: str | Path | None = None
 
 
 @dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
@@ -82,6 +82,7 @@ class ApidocDefaults:
     no_headings: bool
     module_first: bool
     implicit_namespaces: bool
+    template_dir: str | Path | None
 
     @classmethod
     def from_config(cls, config: Config, /) -> Self:
@@ -96,4 +97,5 @@ def from_config(cls, config: Config, /) -> Self:
             no_headings=config.apidoc_no_headings,
             module_first=config.apidoc_module_first,
             implicit_namespaces=config.apidoc_implicit_namespaces,
+            template_dir=config.apidoc_template_dir,
         )

tests/roots/test-ext-apidoc-template-dir/_templates/custom/module.rst.jinja

@@ -0,0 +1,7 @@
+.. custom-template-marker
+
+{{ qualname }} documented with the custom template.
+
+.. automodule:: {{ qualname }}
+   :members:
+

tests/roots/test-ext-apidoc-template-dir/_templates/default/module.rst.jinja

@@ -0,0 +1,7 @@
+.. default-template-marker
+
+{{ qualname }} documented with the default template.
+
+.. automodule:: {{ qualname }}
+   :members:
+

tests/roots/test-ext-apidoc-template-dir/conf.py

@@ -0,0 +1,15 @@
+extensions = ['sphinx.ext.apidoc']
+
+apidoc_separate_modules = True
+apidoc_template_dir = '_templates/default'
+apidoc_modules = [
+    {
+        'path': 'src/pkg_default',
+        'destination': 'generated/default',
+    },
+    {
+        'path': 'src/pkg_custom',
+        'destination': 'generated/custom',
+        'template_dir': '_templates/custom',
+    },
+]

tests/roots/test-ext-apidoc-template-dir/index.rst

@@ -0,0 +1,6 @@
+Test apidoc template directory
+==============================
+
+This project exercises the per-module ``template_dir`` support added to the
+``sphinx.ext.apidoc`` extension.
+