Template rework

ablog/__init__.py

@@ -6,6 +6,9 @@
 from glob import glob
 from pathlib import PurePath
 
+from sphinx.builders.latex import LaTeXBuilder
+from sphinx.jinja2glue import BuiltinTemplateLoader, SphinxFileSystemLoader
+
 from .blog import CONFIG, Blog
 from .post import (
     CheckFrontMatter,
@@ -22,12 +25,23 @@
 )
 from .version import version as __version__
 
+PKGDIR = os.path.abspath(os.path.dirname(__file__))
+
+
 __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 arepage sections.
+    Return anchor string for posts that are page sections.
     """
     if post.section:
         return "#" + post.section
@@ -59,6 +73,55 @@ def html_page_context(app, pagename, templatename, context, doctree):
             context["feed_title"] = blog.blog_title
 
 
+def config_inited(app, config):
+    # 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 builder_inited(app):
+    if isinstance(app.builder, LaTeXBuilder) or app.config.skip_injecting_base_ablog_templates:
+        return
+    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 "
+            "`skip_injecting_base_ablog_templates = 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()))
+
+
 def setup(app):
     """
     Setup ABlog extension.
@@ -68,6 +131,7 @@ def setup(app):
     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)
@@ -86,27 +150,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,45 +91,46 @@ 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))),
+    ("skip_injecting_base_ablog_templates", False, True),
 ]
 TOMORROW = datetime.today() + dtmod.timedelta(1)
 TOMORROW = TOMORROW.replace(hour=0, minute=0, second=0, microsecond=0)
 FUTURE = datetime(9999, 12, 31)
 
 
 def revise_pending_xrefs(doctree, docname):
-    for node in doctree.traverse(addnodes.pending_xref):
+    for node in doctree.findall(addnodes.pending_xref):
         node["refdoc"] = docname
 
 

ablog/locales/ca/LC_MESSAGES/sphinx.po

@@ -22,31 +22,31 @@ msgstr ""
 msgid "Updated on "
 msgstr "Actualitzat el "
 
-#: ablog/post.py:601 ablog/templates/authors.html:2
+#: ablog/post.py:601 ablog/templates/ablog/authors.html:2
 msgid "Authors"
 msgstr "Autors"
 
 #: ablog/post.py:601 ablog/post.py:683
 msgid "Posts by"
 msgstr "Publicacions de"
 
-#: ablog/post.py:602 ablog/templates/locations.html:3
+#: ablog/post.py:602 ablog/templates/ablog/locations.html:3
 msgid "Locations"
 msgstr "Ubicacions"
 
 #: ablog/post.py:602 ablog/post.py:684
 msgid "Posts from"
 msgstr "Publicacions des de"
 
-#: ablog/post.py:603 ablog/templates/languages.html:3
+#: ablog/post.py:603 ablog/templates/ablog/languages.html:3
 msgid "Languages"
 msgstr "Idiomes"
 
 #: ablog/post.py:603 ablog/post.py:604 ablog/post.py:685 ablog/post.py:686
 msgid "Posts in"
 msgstr "Publicacions en"
 
-#: ablog/post.py:604 ablog/templates/categories.html:3
+#: ablog/post.py:604 ablog/templates/ablog/categories.html:3
 msgid "Categories"
 msgstr "Categories"
 
@@ -58,8 +58,8 @@ msgstr "Totes les publicacions"
 msgid "Posted in"
 msgstr "Publicat al"
 
-#: ablog/post.py:606 ablog/templates/postcard2.html:57
-#: ablog/templates/tagcloud.html:2
+#: ablog/post.py:606 ablog/templates/ablog/postcard2.html:57
+#: ablog/templates/ablog/tagcloud.html:2
 msgid "Tags"
 msgstr "Etiquetes"
 
@@ -79,46 +79,46 @@ msgstr "Totes les"
 msgid "Drafts"
 msgstr "Borradors"
 
-#: ablog/templates/archives.html:3
+#: ablog/templates/ablog/archives.html:3
 msgid "Archives"
 msgstr "Arxius"
 
-#: ablog/templates/collection.html:47
+#: ablog/templates/ablog/collection.html:47
 msgid "Read more ..."
 msgstr "Llegir-ne més ..."
 
-#: ablog/templates/postcard2.html:5
+#: ablog/templates/ablog/postcard2.html:5
 msgid "Update"
 msgstr "Actualització"
 
-#: ablog/templates/postcard2.html:12
+#: ablog/templates/ablog/postcard2.html:12
 msgid "Author"
 msgstr "Autor"
 
-#: ablog/templates/postcard2.html:24
+#: ablog/templates/ablog/postcard2.html:24
 msgid "Location"
 msgstr "Ubicació"
 
-#: ablog/templates/postcard2.html:35
+#: ablog/templates/ablog/postcard2.html:35
 msgid "Language"
 msgstr "Idioma"
 
-#: ablog/templates/postcard2.html:46
+#: ablog/templates/ablog/postcard2.html:46
 msgid "Category"
 msgstr "Categoria"
 
-#: ablog/templates/postcard2.html:60
+#: ablog/templates/ablog/postcard2.html:60
 msgid "Tag"
 msgstr "Etiqueta"
 
-#: ablog/templates/postnavy.html:5
+#: ablog/templates/ablog/postnavy.html:5
 msgid "Previous"
 msgstr "Anterior"
 
-#: ablog/templates/postnavy.html:15
+#: ablog/templates/ablog/postnavy.html:15
 msgid "Next"
 msgstr "Següent"
 
-#: ablog/templates/recentposts.html:3
+#: ablog/templates/ablog/recentposts.html:3
 msgid "Recent Posts"
 msgstr "Publicacions recents"