Support and prefer ``.jinja`` to ``_t`` for static templates (#11165)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

9 files changed, 141 insertions, 10 deletions

diff --git a/tests/roots/test-html_assets/extra/API.html_t b/tests/roots/test-html_assets/extra/API.html.jinja
index 34ecd9df1..34ecd9df1 100644
--- a/tests/roots/test-html_assets/extra/API.html_t
+++ b/tests/roots/test-html_assets/extra/API.html.jinja
diff --git a/tests/roots/test-html_assets/static/API.html_t b/tests/roots/test-html_assets/static/API.html.jinja
index 34ecd9df1..34ecd9df1 100644
--- a/tests/roots/test-html_assets/static/API.html_t
+++ b/tests/roots/test-html_assets/static/API.html.jinja
diff --git a/tests/roots/test-latex-table/_mytemplates/latex/longtable.tex_t b/tests/roots/test-latex-table/_mytemplates/latex/longtable.tex.jinja
index e2cb1db0a..e2cb1db0a 100644
--- a/tests/roots/test-latex-table/_mytemplates/latex/longtable.tex_t
+++ b/tests/roots/test-latex-table/_mytemplates/latex/longtable.tex.jinja
diff --git a/tests/roots/test-latex-table/_mytemplates/latex/tabulary.tex_t b/tests/roots/test-latex-table/_mytemplates/latex/tabulary.tex_t
new file mode 100644
index 000000000..c7afd28c5
--- /dev/null
+++ b/tests/roots/test-latex-table/_mytemplates/latex/tabulary.tex_t
@@ -0,0 +1,2 @@
+<# TODO: deprecate '_t' template suffix support after 2024-12-31 #>
+AU REVOIR, KANIGGETS
diff --git a/tests/roots/test-theming/test_theme/staticfiles/static/statictmpl.html_t b/tests/roots/test-theming/test_theme/staticfiles/static/statictmpl.html.jinja
index 4ab292b42..4ab292b42 100644
--- a/tests/roots/test-theming/test_theme/staticfiles/static/statictmpl.html_t
+++ b/tests/roots/test-theming/test_theme/staticfiles/static/statictmpl.html.jinja
diff --git a/tests/test_build_html.py b/tests/test_build_html.py
index 013c09bdb..c5c84f8b1 100644
--- a/tests/test_build_html.py
+++ b/tests/test_build_html.py
@@ -1153,7 +1153,7 @@ def test_html_assets(app):
     # html_extra_path
     assert (app.outdir / '.htaccess').exists()
     assert not (app.outdir / '.htpasswd').exists()
-    assert (app.outdir / 'API.html_t').exists()
+    assert (app.outdir / 'API.html.jinja').exists()
     assert (app.outdir / 'css/style.css').exists()
     assert (app.outdir / 'rimg.png').exists()
     assert not (app.outdir / '_build' / 'index.html').exists()
diff --git a/tests/test_build_latex.py b/tests/test_build_latex.py
index e39ac303c..5dce900e2 100644
--- a/tests/test_build_latex.py
+++ b/tests/test_build_latex.py
@@ -1379,6 +1379,10 @@ def test_latex_table_custom_template_caseA(app, status, warning):
     result = (app.outdir / 'python.tex').read_text(encoding='utf8')
     assert 'SALUT LES COPAINS' in result
 
+    # # TODO: deprecate '_t' template suffix support after 2024-12-31
+    assert 'TODO' not in result
+    assert 'AU REVOIR, KANIGGETS' in result
+
 
 @pytest.mark.sphinx('latex', testroot='latex-table',
                     confoverrides={'templates_path': ['_mytemplates']})
diff --git a/tests/test_deprecation.py b/tests/test_deprecation.py
new file mode 100644
index 000000000..77a4af731
--- /dev/null
+++ b/tests/test_deprecation.py
@@ -0,0 +1,114 @@
+import warnings
+from pathlib import Path
+
+import pytest
+
+from sphinx import deprecation
+
+
+def test_old_jinja_suffix_warning_is_warning():
+    assert isinstance(deprecation.OldJinjaSuffixWarning, type)
+    assert issubclass(deprecation.OldJinjaSuffixWarning, Warning)
+    assert issubclass(deprecation.OldJinjaSuffixWarning, PendingDeprecationWarning)
+
+    with pytest.warns(deprecation.OldJinjaSuffixWarning):
+        warnings.warn('test_1', category=deprecation.OldJinjaSuffixWarning)
+
+    with pytest.warns(PendingDeprecationWarning):
+        warnings.warn('test_2', category=deprecation.OldJinjaSuffixWarning)
+
+    with pytest.warns(Warning):
+        warnings.warn('test_3', category=deprecation.OldJinjaSuffixWarning)
+
+
+def test_old_jinja_suffix_warning_simplefilter_always(recwarn):
+    assert len(recwarn) == 0
+    warnings.resetwarnings()
+
+    warnings.simplefilter('always', category=deprecation.OldJinjaSuffixWarning)
+    warnings.warn('test_simplefilter_always', category=deprecation.OldJinjaSuffixWarning)
+
+    assert len(recwarn) == 1
+    caught_warning = recwarn[0]
+    assert caught_warning.category is deprecation.OldJinjaSuffixWarning
+    assert str(caught_warning.message) == 'test_simplefilter_always'
+
+
+def test_old_jinja_suffix_warning_filterwarnings_always(recwarn):
+    assert len(recwarn) == 0
+    warnings.resetwarnings()
+
+    warnings.filterwarnings('always', category=deprecation.OldJinjaSuffixWarning)
+    warnings.warn('test_filterwarnings_always', category=deprecation.OldJinjaSuffixWarning)
+
+    assert len(recwarn) == 1
+    caught_warning = recwarn[0]
+    assert caught_warning.category is deprecation.OldJinjaSuffixWarning
+    assert str(caught_warning.message) == 'test_filterwarnings_always'
+
+
+def test_old_jinja_suffix_warning_simplefilter_ignore(recwarn):
+    assert len(recwarn) == 0
+    warnings.resetwarnings()
+
+    warnings.simplefilter('ignore', deprecation.OldJinjaSuffixWarning)
+    warnings.warn('test_simplefilter_ignore', category=deprecation.OldJinjaSuffixWarning)
+
+    assert len(recwarn) == 0
+
+
+def test_old_jinja_suffix_warning_filterwarnings_ignore(recwarn):
+    assert len(recwarn) == 0
+    warnings.resetwarnings()
+
+    warnings.filterwarnings('ignore', category=deprecation.OldJinjaSuffixWarning)
+    warnings.warn('test_filterwarnings_ignore', category=deprecation.OldJinjaSuffixWarning)
+
+    assert len(recwarn) == 0
+
+
+def test__old_jinja_template_suffix_no_warning_css(recwarn):
+    assert len(recwarn) == 0
+    warnings.resetwarnings()
+    warnings.simplefilter('always', category=deprecation.OldJinjaSuffixWarning)
+
+    deprecation._old_jinja_template_suffix_warning('template.css')
+
+    assert len(recwarn) == 0
+
+
+def test__old_jinja_template_suffix_no_warning_jinja(recwarn):
+    assert len(recwarn) == 0
+    warnings.resetwarnings()
+    warnings.simplefilter('always', category=deprecation.OldJinjaSuffixWarning)
+
+    deprecation._old_jinja_template_suffix_warning('template.css.jinja')
+
+    assert len(recwarn) == 0
+
+
+def test__old_jinja_template_suffix_warning__t():
+    with pytest.warns(deprecation.OldJinjaSuffixWarning,
+                      match=r"the '_t' suffix for Jinja templates is deprecated"):
+        deprecation._old_jinja_template_suffix_warning('template.css_t')
+
+
+def test__old_jinja_template_suffix_warning_stacklevel():
+    # _old_jinja_template_suffix_warning is only called within functions that
+    # use template files.
+    def do_something_with_templates(filename):
+        deprecation._old_jinja_template_suffix_warning(filename)
+
+    # TOJTSWS line number marker
+    with pytest.warns(deprecation.OldJinjaSuffixWarning) as caught:
+        do_something_with_templates('template.css_t')
+
+    lines = [b''] + Path(__file__).read_bytes().splitlines()
+    line_number = lines.index(b'    # TOJTSWS line number marker') + 2
+
+    assert len(caught) == 1
+    caught_warning = caught[0]
+    assert caught_warning.category is deprecation.OldJinjaSuffixWarning
+    assert "the '_t' suffix for Jinja templates is deprecated" in str(caught_warning.message)
+    assert caught_warning.filename == __file__
+    assert caught_warning.lineno == line_number
diff --git a/tests/test_util_fileutil.py b/tests/test_util_fileutil.py
index 7ea12508c..86f2c96b4 100644
--- a/tests/test_util_fileutil.py
+++ b/tests/test_util_fileutil.py
@@ -3,7 +3,7 @@
 from unittest import mock
 
 from sphinx.jinja2glue import BuiltinTemplateLoader
-from sphinx.util.fileutil import copy_asset, copy_asset_file
+from sphinx.util.fileutil import _template_basename, copy_asset, copy_asset_file
 
 
 class DummyTemplateLoader(BuiltinTemplateLoader):
@@ -28,9 +28,9 @@ def test_copy_asset_file(tempdir):
     assert src.read_text(encoding='utf8') == dest.read_text(encoding='utf8')
 
     # copy template file
-    src = (tempdir / 'asset.txt_t')
+    src = (tempdir / 'asset.txt.jinja')
     src.write_text('# {{var1}} data')
-    dest = (tempdir / 'output.txt_t')
+    dest = (tempdir / 'output.txt.jinja')
 
     copy_asset_file(src, dest, {'var1': 'template'}, renderer)
     assert not dest.exists()
@@ -38,7 +38,7 @@ def test_copy_asset_file(tempdir):
     assert (tempdir / 'output.txt').read_text(encoding='utf8') == '# template data'
 
     # copy template file to subdir
-    src = (tempdir / 'asset.txt_t')
+    src = (tempdir / 'asset.txt.jinja')
     src.write_text('# {{var1}} data')
     subdir1 = (tempdir / 'subdir')
     subdir1.makedirs()
@@ -48,14 +48,14 @@ def test_copy_asset_file(tempdir):
     assert (subdir1 / 'asset.txt').read_text(encoding='utf8') == '# template data'
 
     # copy template file without context
-    src = (tempdir / 'asset.txt_t')
+    src = (tempdir / 'asset.txt.jinja')
     subdir2 = (tempdir / 'subdir2')
     subdir2.makedirs()
 
     copy_asset_file(src, subdir2)
     assert not (subdir2 / 'asset.txt').exists()
-    assert (subdir2 / 'asset.txt_t').exists()
-    assert (subdir2 / 'asset.txt_t').read_text(encoding='utf8') == '# {{var1}} data'
+    assert (subdir2 / 'asset.txt.jinja').exists()
+    assert (subdir2 / 'asset.txt.jinja').read_text(encoding='utf8') == '# {{var1}} data'
 
 
 def test_copy_asset(tempdir):
@@ -65,12 +65,12 @@ def test_copy_asset(tempdir):
     source = (tempdir / 'source')
     source.makedirs()
     (source / 'index.rst').write_text('index.rst', encoding='utf8')
-    (source / 'foo.rst_t').write_text('{{var1}}.rst', encoding='utf8')
+    (source / 'foo.rst.jinja').write_text('{{var1}}.rst', encoding='utf8')
     (source / '_static').makedirs()
     (source / '_static' / 'basic.css').write_text('basic.css', encoding='utf8')
     (source / '_templates').makedirs()
     (source / '_templates' / 'layout.html').write_text('layout.html', encoding='utf8')
-    (source / '_templates' / 'sidebar.html_t').write_text('sidebar: {{var2}}', encoding='utf8')
+    (source / '_templates' / 'sidebar.html.jinja').write_text('sidebar: {{var2}}', encoding='utf8')
 
     # copy a single file
     assert not (tempdir / 'test1').exists()
@@ -101,3 +101,14 @@ def test_copy_asset(tempdir):
     assert not (destdir / '_static' / 'basic.css').exists()
     assert (destdir / '_templates' / 'layout.html').exists()
     assert not (destdir / '_templates' / 'sidebar.html').exists()
+
+
+def test_template_basename():
+    assert not _template_basename("asset.txt")
+    assert _template_basename("asset.txt.jinja") == "asset.txt"
+    assert _template_basename("sidebar.html.jinja") == "sidebar.html"
+
+
+def test_legacy_template_basename():
+    # TODO: deprecate '_t' template suffix support after 2024-12-31
+    assert _template_basename("asset.txt_t") == "asset.txt"