apidoc: Restore support for legacy '_t'-suffix template files (#12929)

Co-authored-by: Adam Turner <[email protected]>

CHANGES.rst

@@ -107,6 +107,9 @@ Bugs fixed
 * #12844: Restore support for ``:noindex:`` for the :rst:dir:`js:module`
   and :rst:dir:`py:module` directives.
   Patch by Stephen Finucane.
+* #12916: Restore support for custom templates named with the legacy ``_t``
+  suffix during ``apidoc`` RST rendering (regression in 7.4.0).
+  Patch by James Addison.
 
 Testing
 -------

sphinx/jinja2glue.py

@@ -119,11 +119,22 @@ class SphinxFileSystemLoader(FileSystemLoader):
     def get_source(
         self, environment: Environment, template: str
     ) -> tuple[str, str, Callable[[], bool]]:
+        if template.endswith('.jinja'):
+            legacy_suffix = '_t'
+            legacy_template = template.removesuffix('.jinja') + legacy_suffix
+        else:
+            legacy_template = None
+
         for searchpath in self.searchpath:
             filename = path.join(searchpath, template)
             f = open_if_exists(filename)
             if f is not None:
                 break
+            if legacy_template is not None:
+                filename = path.join(searchpath, legacy_template)
+                f = open_if_exists(filename)
+                if f is not None:
+                    break
         else:
             raise TemplateNotFound(template)
 

tests/roots/test-apidoc-custom-templates/_templates/module.rst.jinja

@@ -0,0 +1,2 @@
+The Jinja module template was found!
+------------------------------------

tests/roots/test-apidoc-custom-templates/_templates/module.rst_t

@@ -0,0 +1,2 @@
+The legacy module template was found!
+-------------------------------------

tests/roots/test-apidoc-custom-templates/_templates/package.rst_t

@@ -0,0 +1,2 @@
+The legacy package template was found!
+--------------------------------------

tests/test_extensions/test_ext_apidoc.py

@@ -53,6 +53,41 @@ def test_simple(make_app, apidoc):
     print(app._warning.getvalue())
 
 
+@pytest.mark.apidoc(
+    coderoot='test-apidoc-custom-templates',
+    options=[
+        '--separate',
+        '--templatedir=tests/roots/test-apidoc-custom-templates/_templates',
+    ],
+)
+def test_custom_templates(make_app, apidoc):
+    outdir = apidoc.outdir
+    assert (outdir / 'conf.py').is_file()
+    assert (outdir / 'index.rst').is_file()
+
+    template_dir = apidoc.coderoot / '_templates'
+    assert sorted(template_dir.iterdir()) == [
+        template_dir / 'module.rst.jinja',
+        template_dir / 'module.rst_t',
+        template_dir / 'package.rst_t',
+    ]
+
+    app = make_app('text', srcdir=outdir)
+    app.build()
+
+    builddir = outdir / '_build' / 'text'
+
+    # Assert that the legacy filename is discovered
+    with open(builddir / 'mypackage.txt', encoding='utf-8') as f:
+        txt = f.read()
+        assert 'The legacy package template was found!' in txt
+
+    # Assert that the new filename is preferred
+    with open(builddir / 'mypackage.mymodule.txt', encoding='utf-8') as f:
+        txt = f.read()
+        assert 'The Jinja module template was found!' in txt
+
+
 @pytest.mark.apidoc(
     coderoot='test-apidoc-pep420/a',
     options=['--implicit-namespaces'],