Add THEME_TEMPLATE_OVERRIDES. Refs 2021

Allow for overriding individual templates from the theme by configuring
the Jinja2 `Environment` loader to search for templates in the
`THEME_TEMPLATE_OVERRIDES` path before the theme's `templates/`
directory.

docs/settings.rst

@@ -700,6 +700,14 @@ Template pages
    separate templates from the theme.  Example: projects, resume, profile ...
    These templates need to use ``DIRECT_TEMPLATES`` setting.
 
+.. data:: THEME_TEMPLATE_OVERRIDES = []
+
+   A list of paths you want Jinja2 to search for templates before searching the
+   theme's ``templates/`` directory.  Allows for overriding individual theme
+   template files without having to fork an existing theme.  Jinja2 searches in
+   the following order: files in ``THEME_TEMPLATE_OVERRIDES`` first, theme's
+   ``templates/``
+
 
 Metadata
 ========

pelican/generators.py

@@ -52,6 +52,7 @@ class Generator(object):
         # templates cache
         self._templates = {}
         self._templates_path = []
+        self._templates_path += self.settings['THEME_TEMPLATE_OVERRIDES']
         self._templates_path.append(os.path.expanduser(
             os.path.join(self.theme, 'templates')))
         self._templates_path += self.settings['EXTRA_TEMPLATES_PATHS']

pelican/settings.py

@@ -97,6 +97,7 @@ DEFAULT_CONFIG = {
     'RELATIVE_URLS': False,
     'DEFAULT_LANG': 'en',
     'DIRECT_TEMPLATES': ['index', 'tags', 'categories', 'authors', 'archives'],
+    'THEME_TEMPLATE_OVERRIDES': [],
     'EXTRA_TEMPLATES_PATHS': [],
     'PAGINATED_DIRECT_TEMPLATES': ['index'],
     'PELICAN_CLASS': 'pelican.Pelican',
@@ -380,6 +381,7 @@ def configure_settings(settings):
         'ARTICLE_EXCLUDES',
         'DEFAULT_METADATA',
         'DIRECT_TEMPLATES',
+        'THEME_TEMPLATE_OVERRIDES',
         'EXTRA_TEMPLATES_PATHS',
         'FILES_TO_COPY',
         'IGNORE_FILES',

pelican/tests/test_generators.py

@@ -118,6 +118,32 @@ class TestGenerator(unittest.TestCase):
                          generator.env.comment_end_string)
 
 
+    # def test_get_templat_with_theme_overrides(self):
+    #     override_dirs = (os.path.join(CUR_DIR, 'theme_overrides', 'level1'),
+    #                      os.path.join(CUR_DIR, 'theme_overrides', 'level2'))
+    #     self.settings['THEME_TEMPLATE_OVERRIDES'] = override_dirs
+    #     generator = Generator(
+    #         context=self.settings.copy(),
+    #         settings=self.settings,
+    #         path=CUR_DIR,
+    #         theme=self.settings['THEME'],
+    #         output_path=None)
+
+    #     filename = generator.get_template('article').filename
+    #     self.assertEqual(override_dirs[0], os.path.dirname(filename))
+    #     self.assertEqual('article.html', os.path.basename(filename))
+
+    #     filename = generator.get_template('authors').filename
+    #     self.assertEqual(override_dirs[1], os.path.dirname(filename))
+    #     self.assertEqual('authors.html', os.path.basename(filename))
+
+    #     filename = generator.get_template('taglist').filename
+    #     self.assertEqual(os.path.join(self.settings['THEME'], 'templates'),
+    #                      os.path.dirname(filename))
+    #     self.assertNotIn(os.path.dirname(filename), override_dirs)
+    #     self.assertEqual('taglist.html', os.path.basename(filename))
+
+
 class TestArticlesGenerator(unittest.TestCase):
 
     @classmethod

pelican/tests/theme_overrides/level1/article.html

@@ -0,0 +1,4 @@
+<!--
+  This file is only here to test the `THEME_TEMPLATE_OVERRIDES` configuration
+  setting.
+-->

pelican/tests/theme_overrides/level2/article.html

@@ -0,0 +1,4 @@
+<!--
+  This file is only here to test the `THEME_TEMPLATE_OVERRIDES` configuration
+  setting.
+-->

pelican/tests/theme_overrides/level2/authors.html

@@ -0,0 +1,4 @@
+<!--
+  This file is only here to test the `THEME_TEMPLATE_OVERRIDES` configuration
+  setting.
+-->