WIP - REBASE THIS OUT LATER

Author: nabobalis

ablog/__init__.py

@@ -6,6 +6,8 @@
 from glob import glob
 from pathlib import PurePath
 
+from sphinx.jinja2glue import BuiltinTemplateLoader, SphinxFileSystemLoader
+
 from .blog import CONFIG, Blog
 from .post import (
     CheckFrontMatter,
@@ -28,6 +30,14 @@
 __all__ = ["setup"]
 
 
+def get_html_templates_path():
+    """
+    Return path to ABlog templates folder.
+    """
+    pkgdir = os.path.abspath(os.path.dirname(__file__))
+    return os.path.join(pkgdir, "templates")
+
+
 def anchor(post):
     """
     Return anchor string for posts that are page sections.
@@ -62,6 +72,52 @@ def html_page_context(app, pagename, templatename, context, doctree):
             context["feed_title"] = blog.blog_title
 
 
+def builder_inited(app):
+    if not app.config.inject_templates_after_theme:
+        if not isinstance(app.builder.templates, BuiltinTemplateLoader):
+            raise Exception(
+                "Ablog does not know how to inject templates into with custom "
+                "template bridges. You can use `ablog.get_html_templates_path()` to "
+                "get the path to add in your custom template bridge and set "
+                "`inject_templates_after_theme = False` in your "
+                "`conf.py` file."
+            )
+        if get_html_templates_path() in app.config.templates_path:
+            raise Exception(
+                "Found the path from `ablog.get_html_templates_path()` in the "
+                "`templates_path` variable from `conf.py`. Doing so interferes "
+                "with Ablog's ability to stay compatible with Sphinx themes that "
+                "support it out of the box. Please remove `get_html_templates_path` "
+                "from `templates_path` in your `conf.py` to resolve this."
+            )
+    theme = app.builder.theme
+    loaders = app.builder.templates.loaders
+    templatepathlen = app.builder.templates.templatepathlen
+    if theme.get_config("ablog", "inject_templates_after_theme", False):
+        # Inject *after* the user templates and the theme templates,
+        # allowing themes to override the templates provided by this
+        # extension while those templates still serve as a fallback.
+        loaders.append(SphinxFileSystemLoader(get_html_templates_path()))
+    else:
+        # Inject *after* the user templates and *before* the theme
+        # templates. This enables ablog to provide support for themes
+        # that don't support it out-of-the-box, like alabaster.
+        loaders.insert(templatepathlen, SphinxFileSystemLoader(get_html_templates_path()))
+
+    # Automatically identify any blog posts if a pattern is specified in the config
+    if isinstance(app.config.blog_post_pattern, str):
+        app.config.blog_post_pattern = [app.config.blog_post_pattern]
+    matched_patterns = []
+    for pattern in app.config.blog_post_pattern:
+        pattern = os.path.join(app.srcdir, pattern)
+        # make sure that blog post paths have forward slashes even on windows
+        matched_patterns.extend(
+            PurePath(ii).relative_to(app.srcdir).with_suffix("").as_posix()
+            for ii in glob(pattern, recursive=True)
+        )
+    app.config.matched_blog_posts = matched_patterns
+
+
 def setup(app):
     """
     Setup ABlog extension.
@@ -70,7 +126,7 @@ def setup(app):
         app.add_config_value(*args[:3])
     app.add_directive("post", PostDirective)
     app.add_directive("postlist", PostListDirective)
-    app.connect("config-inited", config_inited)
+    app.connect("builder-inited", builder_inited)
     app.connect("doctree-read", process_posts)
     app.connect("env-purge-doc", purge_posts)
     app.connect("doctree-resolved", process_postlist)
@@ -89,27 +145,3 @@ def setup(app):
     locale_dir = os.path.join(pkgdir, "locales")
     app.config.locale_dirs.append(locale_dir)
     return {"version": __version__}  # identifies the version of our extension
-
-
-def config_inited(app, config):
-    app.config.templates_path.append(get_html_templates_path())
-    # Automatically identify any blog posts if a pattern is specified in the config
-    if isinstance(config.blog_post_pattern, str):
-        config.blog_post_pattern = [config.blog_post_pattern]
-    matched_patterns = []
-    for pattern in config.blog_post_pattern:
-        pattern = os.path.join(app.srcdir, pattern)
-        # make sure that blog post paths have forward slashes even on windows
-        matched_patterns.extend(
-            PurePath(ii).relative_to(app.srcdir).with_suffix("").as_posix()
-            for ii in glob(pattern, recursive=True)
-        )
-    app.config.matched_blog_posts = matched_patterns
-
-
-def get_html_templates_path():
-    """
-    Return path to ABlog templates folder.
-    """
-    pkgdir = os.path.abspath(os.path.dirname(__file__))
-    return os.path.join(pkgdir, "templates")

ablog/blog.py

@@ -91,37 +91,38 @@ def verify_fn(key, value, config):
 CONFIG = [
     # name, default, rebuild, verify_fn
     # where verify_fn is (key, value, app.config) --> value, throwing a KeyError if the value isn't right
-    ("blog_path", "blog", True, require_config_type(str)),
-    ("blog_title", "Blog", True, require_config_type(str)),
-    ("blog_baseurl", "", True, require_config_type(str)),
     ("blog_archive_titles", None, False, require_config_type(bool)),
+    ("blog_authors", {}, True, require_config_full_name_link_dict()),
+    ("blog_baseurl", "", True, require_config_type(str)),
+    ("blog_default_author", None, True, require_config_str_or_list_lookup("blog_authors")),
+    ("blog_default_language", None, True, require_config_str_or_list_lookup("blog_languages")),
+    ("blog_default_location", None, True, require_config_str_or_list_lookup("blog_locations")),
     ("blog_feed_archives", False, True),
     ("blog_feed_fulltext", False, True),
+    ("blog_feed_length", None, None),
     ("blog_feed_subtitle", None, True),
-    ("blog_feed_titles", None, False),
     ("blog_feed_templates", {"atom": {}}, True),
-    ("blog_feed_length", None, None),
-    ("blog_authors", {}, True, require_config_full_name_link_dict()),
-    ("blog_default_author", None, True, require_config_str_or_list_lookup("blog_authors")),
-    ("blog_locations", {}, True, require_config_full_name_link_dict()),
-    ("blog_default_location", None, True, require_config_str_or_list_lookup("blog_locations")),
+    ("blog_feed_titles", None, False),
     ("blog_languages", {}, True, require_config_full_name_link_dict()),
-    ("blog_default_language", None, True, require_config_str_or_list_lookup("blog_languages")),
-    ("fontawesome_link_cdn", None, True),
-    ("fontawesome_included", False, True, require_config_type(bool)),
+    ("blog_locations", {}, True, require_config_full_name_link_dict()),
+    ("blog_path", "blog", True, require_config_type(str)),
+    ("blog_post_pattern", [], True, require_config_type((str, list))),
+    ("blog_title", "Blog", True, require_config_type(str)),
+    ("disqus_drafts", False, True),
+    ("disqus_pages", False, True),
+    ("disqus_shortname", None, True),
     ("fontawesome_css_file", "", True, require_config_type(str)),
-    ("post_date_format", "%d %B %Y", True, require_config_type(str)),
-    ("post_date_format_short", "%d %B", True, require_config_type(str)),
-    ("post_auto_orphan", True, True, require_config_type(bool)),
-    ("post_auto_image", 0, True),
+    ("fontawesome_included", False, True, require_config_type(bool)),
+    ("fontawesome_link_cdn", None, True),
+    ("post_always_section", False, True),
     ("post_auto_excerpt", 1, True),
+    ("post_auto_image", 0, True),
+    ("post_auto_orphan", True, True, require_config_type(bool)),
+    ("post_date_format_short", "%d %B", True, require_config_type(str)),
+    ("post_date_format", "%d %B %Y", True, require_config_type(str)),
     ("post_redirect_refresh", 5, True),
-    ("post_always_section", False, True),
     ("post_show_prev_next", True, True),
-    ("disqus_shortname", None, True),
-    ("disqus_drafts", False, True),
-    ("disqus_pages", False, True),
-    ("blog_post_pattern", [], True, require_config_type((str, list))),
+    ("inject_templates_after_theme", False, True),
 ]
 TOMORROW = datetime.today() + dtmod.timedelta(1)
 TOMORROW = TOMORROW.replace(hour=0, minute=0, second=0, microsecond=0)

ablog/post.py

@@ -554,7 +554,7 @@ def generate_archive_pages(app):
     blog = Blog(app)
     for post in blog.posts:
         for redirect in post.redirect:
-            yield (redirect, {"redirect": post.docname, "post": post}, "redirect.html")
+            yield (redirect, {"redirect": post.docname, "post": post}, "ablog/redirect.html")
     found_docs = app.env.found_docs
     atom_feed = bool(blog.blog_baseurl)
     feed_archives = blog.blog_feed_archives
@@ -571,7 +571,7 @@ def generate_archive_pages(app):
             continue
         context = {"parents": [], "title": title, "header": header, "catalog": catalog, "summary": True}
         if catalog.docname not in found_docs:
-            yield (catalog.docname, context, "catalog.html")
+            yield (catalog.docname, context, "ablog/catalog.html")
         for collection in catalog:
             if not collection:
                 continue
@@ -586,7 +586,7 @@ def generate_archive_pages(app):
             }
             context["feed_title"] = context["title"]
             if collection.docname not in found_docs:
-                yield (collection.docname, context, "collection.html")
+                yield (collection.docname, context, "ablog/collection.html")
     if 1:
         context = {
             "parents": [],
@@ -598,9 +598,9 @@ def generate_archive_pages(app):
             "feed_path": blog.blog_path,
         }
         docname = blog.posts.docname
-        yield (docname, context, "collection.html")
+        yield (docname, context, "ablog/collection.html")
     context = {"parents": [], "title": _("Drafts"), "collection": blog.drafts, "summary": True}
-    yield (blog.drafts.docname, context, "collection.html")
+    yield (blog.drafts.docname, context, "ablog/collection.html")
 
 
 def generate_atom_feeds(app):

ablog/start.py

@@ -77,6 +77,12 @@ def w(t, ls=80):
 #    'Earth': ('The Blue Planet', 'https://en.wikipedia.org/wiki/Earth),
 # }}
 
+# See https://github.com/sunpy/ablog/pull/144 for the full context
+# This will prevent ablog from overriding any local templates that you might
+# need to use for your project.
+# Default is ``False``.
+# inject_templates_after_theme = False
+
 # -- Blog Post Related --------------------------------------------------------
 
 # Format date for a post.
@@ -215,9 +221,6 @@ def w(t, ls=80):
     'ablog',
 ]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = [ablog.get_html_templates_path(), "{dot}templates"]
-
 # The suffix(es) of source filenames.
 source_suffix = "{suffix}"
 

ablog/templates/ablog/collection.html

@@ -50,7 +50,7 @@ <h2 class="ablog-post-title">
         {% endif %}
         {% endif %}
       </li>
-      {% include "postcard2.html" %}
+      {% include "ablog/postcard2.html" %}
     </ul>
     {{ post.to_html(collection.docname) }}
     <p class="ablog-post-expand"><a href="{{ pathto(post.docname) }}"><em>{{ _("Read more ...") }}</em></a></p>

ablog/templates/ablog/postcard.html

@@ -20,7 +20,7 @@ <h2>
   {% endif %}
 </h2>
 <ul>
-  {% include "postcard2.html" %}
+  {% include "ablog/postcard2.html" %}
 </ul>
 </div>
 {% endif %}

ablog/templates/ablog/page.html ablog/templates/page.htmlablog/templates/ablog/page.html renamed to ablog/templates/page.html

@@ -24,7 +24,7 @@
 {{ body }}
 <div class="section ablog__blog_comments">
   {% if pagename in ablog %}
-  {% include "postnavy.html" %}
+  {% include "ablog/postnavy.html" %}
   {% endif %}
   {% if ablog.disqus_shortname and ablog.blog_baseurl and (not ablog[pagename].nocomments) and ((pagename in ablog and (ablog[pagename].published or ablog.disqus_drafts)) or (not pagename in ablog and ablog.disqus_pages)) %}
   <div class="section ablog__comments">

docs/conf.py

@@ -57,6 +57,7 @@
     "SF": ("San Francisco, CA", "https://en.wikipedia.org/wiki/San_Francisco"),
     "Denizli": ("Denizli, Turkey", "https://en.wikipedia.org/wiki/Denizli"),
 }
+inject_templates_after_theme = False
 blog_languages = {
     "en": ("English", None),
     "nl": ("Nederlands", None),

setup.cfg

@@ -17,7 +17,7 @@ include_package_data = True
 setup_requires =
   setuptools_scm
 install_requires =
-  docutils>=0.19
+  docutils
   feedgen>=0.9.0
   invoke>=1.6.0
   python-dateutil>=2.8.0

setup.py

@@ -29,6 +29,7 @@
     message_extractors={
         "ablog": [
             ("**.py", "python", None),
+            ("templates/**.html", "jinja2", None),
             ("templates/ablog/**.html", "jinja2", None),
         ],
     },