apidoc: allow configuring template directories

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,
         )

sphinx/transforms/i18n.py

@@ -415,7 +415,7 @@ def apply(self, **kwargs: Any) -> None:
             # There is no point in having noqa on literal blocks because
             # they cannot contain references.  Recognizing it would just
             # completely prevent escaping the noqa.  Outside of literal
-            # blocks, one can always write \#noqa.
+            # blocks, one can always write ``\#`` followed by ``noqa``.
             if not isinstance(node, LITERAL_TYPE_NODES):
                 msgstr, _ = parse_noqa(msgstr)
 

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.
+

tests/roots/test-ext-apidoc-template-dir/src/pkg_custom/__init__.py

@@ -0,0 +1 @@
+"""Custom template package."""

tests/roots/test-ext-apidoc-template-dir/src/pkg_custom/module_custom.py

@@ -0,0 +1,5 @@
+"""Example module that should use the custom template."""
+
+
+def ping() -> str:
+    return 'custom template pong'

tests/roots/test-ext-apidoc-template-dir/src/pkg_default/__init__.py

@@ -0,0 +1 @@
+"""Default template package."""

tests/roots/test-ext-apidoc-template-dir/src/pkg_default/module_default.py

@@ -0,0 +1,5 @@
+"""Example module that should use the default template."""
+
+
+def ping() -> str:
+    return 'default template pong'

tests/test_extensions/test_ext_apidoc.py

@@ -3,16 +3,18 @@
 from __future__ import annotations
 
 from collections import namedtuple
+from pathlib import Path
+from shutil import copytree
+from types import SimpleNamespace
 from typing import TYPE_CHECKING
 
 import pytest
 
 import sphinx.ext.apidoc._generate
 from sphinx.ext.apidoc._cli import main as apidoc_main
+from sphinx.ext.apidoc._extension import run_apidoc
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from sphinx.testing.util import SphinxTestApp
 
 _apidoc = namedtuple('_apidoc', 'coderoot,outdir')  # NoQA: PYI024
@@ -96,6 +98,57 @@ def test_custom_templates(make_app, apidoc):
     assert 'The Jinja module template was found!' in txt
 
 
+def test_extension_template_dir_option(rootdir, tmp_path):
+    srcdir = tmp_path / 'project'
+    copytree(rootdir / 'test-ext-apidoc-template-dir', srcdir)
+    config = SimpleNamespace(
+        apidoc_exclude_patterns=[],
+        apidoc_automodule_options=frozenset({
+            'members',
+            'undoc-members',
+            'show-inheritance',
+        }),
+        apidoc_max_depth=4,
+        apidoc_follow_links=False,
+        apidoc_separate_modules=True,
+        apidoc_include_private=False,
+        apidoc_no_headings=False,
+        apidoc_module_first=False,
+        apidoc_implicit_namespaces=False,
+        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',
+            },
+        ],
+    )
+    app = SimpleNamespace(config=config, srcdir=srcdir, confdir=srcdir)
+    run_apidoc(app)
+
+    generated_default = (
+        Path(srcdir) / 'generated' / 'default' / 'pkg_default.module_default.rst'
+    )
+    generated_custom = (
+        Path(srcdir) / 'generated' / 'custom' / 'pkg_custom.module_custom.rst'
+    )
+
+    assert generated_default.is_file()
+    assert generated_custom.is_file()
+
+    default_text = generated_default.read_text(encoding='utf-8')
+    custom_text = generated_custom.read_text(encoding='utf-8')
+
+    assert '.. default-template-marker' in default_text
+    assert '.. custom-template-marker' in custom_text
+    assert '.. custom-template-marker' not in default_text
+
+
 @pytest.mark.apidoc(
     coderoot='test-ext-apidoc-pep420/a',
     options=['--implicit-namespaces'],