From 80c4b65a2a56271f4800ed4b2bab1fb527d17716 Mon Sep 17 00:00:00 2001
From: James Addison <55152140+jayaddison@users.noreply.github.com>
Date: Wed, 2 Oct 2024 23:21:03 +0000
Subject: [PATCH] apidoc: Restore support for legacy '_t'-suffix template files
 (#12929)

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
---
 CHANGES.rst                                   |  3 ++
 sphinx/jinja2glue.py                          | 11 ++++++
 .../_templates/module.rst.jinja               |  2 ++
 .../_templates/module.rst_t                   |  2 ++
 .../_templates/package.rst_t                  |  2 ++
 .../mypackage/__init__.py                     |  0
 .../mypackage/mymodule.py                     |  0
 tests/test_extensions/test_ext_apidoc.py      | 35 +++++++++++++++++++
 8 files changed, 55 insertions(+)
 create mode 100644 tests/roots/test-apidoc-custom-templates/_templates/module.rst.jinja
 create mode 100644 tests/roots/test-apidoc-custom-templates/_templates/module.rst_t
 create mode 100644 tests/roots/test-apidoc-custom-templates/_templates/package.rst_t
 create mode 100644 tests/roots/test-apidoc-custom-templates/mypackage/__init__.py
 create mode 100755 tests/roots/test-apidoc-custom-templates/mypackage/mymodule.py

diff --git a/CHANGES.rst b/CHANGES.rst
index 1a7482024bf..c1d0f410acb 100644
--- a/CHANGES.rst
+++ b/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
 -------
diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py
index 5436900db12..2f6e4e3dc52 100644
--- a/sphinx/jinja2glue.py
+++ b/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)
 
diff --git a/tests/roots/test-apidoc-custom-templates/_templates/module.rst.jinja b/tests/roots/test-apidoc-custom-templates/_templates/module.rst.jinja
new file mode 100644
index 00000000000..fe45792ff82
--- /dev/null
+++ b/tests/roots/test-apidoc-custom-templates/_templates/module.rst.jinja
@@ -0,0 +1,2 @@
+The Jinja module template was found!
+------------------------------------
diff --git a/tests/roots/test-apidoc-custom-templates/_templates/module.rst_t b/tests/roots/test-apidoc-custom-templates/_templates/module.rst_t
new file mode 100644
index 00000000000..4489ab7437c
--- /dev/null
+++ b/tests/roots/test-apidoc-custom-templates/_templates/module.rst_t
@@ -0,0 +1,2 @@
+The legacy module template was found!
+-------------------------------------
diff --git a/tests/roots/test-apidoc-custom-templates/_templates/package.rst_t b/tests/roots/test-apidoc-custom-templates/_templates/package.rst_t
new file mode 100644
index 00000000000..c4b5406b72e
--- /dev/null
+++ b/tests/roots/test-apidoc-custom-templates/_templates/package.rst_t
@@ -0,0 +1,2 @@
+The legacy package template was found!
+--------------------------------------
diff --git a/tests/roots/test-apidoc-custom-templates/mypackage/__init__.py b/tests/roots/test-apidoc-custom-templates/mypackage/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/roots/test-apidoc-custom-templates/mypackage/mymodule.py b/tests/roots/test-apidoc-custom-templates/mypackage/mymodule.py
new file mode 100755
index 00000000000..e69de29bb2d
diff --git a/tests/test_extensions/test_ext_apidoc.py b/tests/test_extensions/test_ext_apidoc.py
index 845405a9edb..36594133996 100644
--- a/tests/test_extensions/test_ext_apidoc.py
+++ b/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'],