Jinja cleanup

doc/src/common/jinja_extensions.py

@@ -1,4 +1,3 @@
-import re
 from html import escape
 from typing import Any
 
@@ -32,19 +31,24 @@ def hexdoc_minify(value: str) -> str:
     return "".join(line.strip() for line in value.splitlines())
 
 
-def hexdoc_block(value: Any, allow_none: bool = False) -> str:
+# TODO: remove this when we do the jinja breaking changes
+def hexdoc_escape(value: Any) -> str:
+    return Markup(escape(str(value)))
+
+
+def hexdoc_block(value: Any) -> str:
     match value:
         case LocalizedStr() | str():
             # use Markup to tell Jinja not to escape this string for us
             lines = str(value).splitlines()
-            return Markup("<br />".join(escape(line) for line in lines))
+            return Markup("<br />".join(hexdoc_escape(line) for line in lines))
         case FormatTree():
             with HTMLStream() as out:
                 with value.style.element(out):
                     for child in value.children:
                         out.write(hexdoc_block(child))
                 return Markup(out.getvalue())
-        case None if allow_none:
+        case None:
             return ""
         case _:
             raise TypeError(value)
@@ -56,5 +60,4 @@ def hexdoc_wrap(value: str, *args: str):
         attributes = " " + " ".join(attributes)
     else:
         attributes = ""
-    # FIXME: hack (also all the incorrect uses of hexdoc_block)
-    return Markup(f"<{tag}{attributes}>{escape(str(value))}</{tag}>")
+    return Markup(f"<{tag}{attributes}>{hexdoc_escape(value)}</{tag}>")

doc/src/hexcasting/scripts/main.py

@@ -12,6 +12,7 @@ from tap import Tap
 from common.jinja_extensions import (
     IncludeRawExtension,
     hexdoc_block,
+    hexdoc_escape,
     hexdoc_minify,
     hexdoc_wrap,
 )
@@ -53,6 +54,7 @@ def main(args: Args) -> None:
         hexdoc_minify=hexdoc_minify,
         hexdoc_block=hexdoc_block,
         hexdoc_wrap=hexdoc_wrap,
+        hexdoc_escape=hexdoc_escape,
     )
 
     # load and render template

doc/templates/book.html.jinja

@@ -1,18 +1,21 @@
 <div class='container'>
+  {# big landing text box - this is optional so addons can disable it if they want #}
   {% if show_landing_text %}
     <header class='jumbotron'>
-      <h1 class='book-title'>
-        {{ book.name }}
-      </h1>
+      <h1 class='book-title'>{{ book.name }}</h1>
       {{ book.landing_text|hexdoc_block }}
     </header>
   {% endif %}
+
+  {# table of contents #}
   <nav>
     {% include "tableofcontents.html.jinja" %}
   </nav>
+
+  {# actual book content (ie. all the categories) #}
   <main class='book-body'>
     {% for category in book.categories.values() %}
-      {% include "category.html.jinja" -%}
+      {% include "category.html.jinja" %}
     {% endfor -%}
   </main>
 </div>

doc/templates/category.html.jinja

@@ -5,9 +5,7 @@
     {{ macros.section_header(category, "h2", "category-title") }}
     {{ category.description|hexdoc_block }}
   {% endcall %}
-  {% for entry in category.entries %}
-    {% if entry.id not in props.blacklist %}
+  {% for entry in category.entries if entry.id not in props.blacklist %}
     {% include "entry.html.jinja" %}
-    {% endif %}
   {% endfor %}
 </section>

doc/templates/entry.html.jinja

@@ -4,7 +4,7 @@
   {% call macros.maybe_spoilered(entry) %}
     {{ macros.section_header(entry, "h3", "entry-title") }}
     {% for page in entry.pages %}
-      {% include page.template %}
+      {%- include page.template -%}
     {% endfor %}
   {% endcall %}
 </div>

doc/templates/macros.html.jinja

@@ -1,16 +1,35 @@
-{% macro permalink(href) %}
-  <a href='#{{ href }}' class='permalink small' title='Permalink'>
-    <i class='bi bi-link-45deg'></i>
-  </a>
-{% endmacro %}
-
-{% macro maybe_spoilered_link(value) %}
-  <a href='#{{ value.id.path }}' class='{{ "spoilered" if value.is_spoiler else "" }}'>
-    {{- value.name|hexdoc_block -}}
+{# jump to top icon in section headers #}
+{% macro jump_to_top() -%}
+  <a href='#table-of-contents' class='permalink small' title='Jump to top'>
+    <i class='bi bi-box-arrow-up'></i>
   </a>
 {%- endmacro %}
 
-{% macro maybe_spoilered(value) %}
+{# link icon in section headers to get a permalink to that section #}
+{% macro permalink(href) -%}
+  <a href='#{{ href }}' class='permalink small' title='Permalink'>
+    <i class='bi bi-link-45deg'></i>
+  </a>
+{%- endmacro %}
+
+{# header for categories and entries #}
+{% macro section_header(value, header_tag, class_name) -%}
+  <{{ header_tag }} class='{{ class_name }} page-header'>
+    {{ value.name|hexdoc_escape }}
+    {{ jump_to_top() }}
+    {{ permalink(value.id.path) }}
+  </{{ header_tag }}>
+{%- endmacro %}
+
+{# link to value.id, with spoiler blur if value is a spoiler #}
+{% macro maybe_spoilered_link(value) -%}
+  <a href='#{{ value.id.path }}' class='{{ "spoilered" if value.is_spoiler else "" }}'>
+    {{- value.name|hexdoc_escape -}}
+  </a>
+{%- endmacro %}
+
+{# macro block which spoiler blurs its content if value is a spoiler #}
+{% macro maybe_spoilered(value) -%}
   {% if value.is_spoiler %}
     <div class='spoilered'>
       {{ caller() }}
@@ -20,21 +39,8 @@
   {% endif %}
 {%- endmacro %}
 
-{% macro jump_to_top() %}
-  <a href='#table-of-contents' class='permalink small' title='Jump to top'>
-    <i class='bi bi-box-arrow-up'></i>
-  </a>
-{%- endmacro %}
-
-{% macro section_header(value, header_tag, class_name) %}
-  <{{ header_tag }} class='{{ class_name }} page-header'>
-    {{ value.name|hexdoc_block }}
-    {{ jump_to_top() }}
-    {{ permalink(value.id.path) }}
-  </{{ header_tag }}>
-{%- endmacro %}
-
-{% macro recipe_block(recipes, result_attribute, description, separator) %}
+{# shows the names of all the recipe results in a list of recipes #}
+{% macro recipe_block(recipes, result_attribute, description, separator) -%}
   <blockquote class='crafting-info'>
     Depicted in the book: {{ description }} {{
       recipes

doc/templates/pages/BrainsweepPage.html.jinja

@@ -1,7 +1,7 @@
-{% extends "pages/PageWithText.html.jinja" %}
+{% extends "pages/Page.html.jinja" %}
 {% include "macros.html.jinja" %}
 
 {% block body %}
   {{ macros.recipe_block([page.recipe], "name", "A mind-flaying recipe producing the", "") }}
-  {{ super() }}
+  {{ page.text|hexdoc_block }}
 {% endblock body %}

doc/templates/pages/LinkPage.html.jinja

@@ -3,6 +3,6 @@
 {% block inner_body %}
   {{- super() }}
   <h4 class='linkout'>
-    <a href='{{ page.url|hexdoc_block }}'>{{ page.link_text }}</a>
+    <a href='{{ page.url|hexdoc_escape }}'>{{ page.link_text }}</a>
   </h4>
 {% endblock inner_body %}

doc/templates/pages/Page.html.jinja

@@ -1,9 +1,12 @@
-{%- if page.anchor -%}
-  {%- set page_anchor_id = entry.id.path ~ "@" ~ page.anchor -%}{# set a variable so children can use this value -#}
+{% if page.anchor %}
+  {# set variable to allow children to use this value too #}
+  {% set page_anchor_id = entry.id.path ~ "@" ~ page.anchor -%}
+
+  {# page content (not required because EmptyPage uses this template directly) -#}
   <div id='{{ page_anchor_id }}'>
-    {% block body scoped %}{% endblock %}{# not required because EmptyPage uses this template directly -#}
+    {% block body scoped %}{% endblock -%}
   </div>
-{%- else -%}
-  {{ self.body() }}{# can't define a block twice in the same template, so just reference it #}
-{%- endif -%}
+{% else %}
+  {{- self.body() }}
+{% endif %}
 <br />

doc/templates/pages/PageWithPattern.html.jinja

@@ -3,6 +3,7 @@
 {% block inner_body %}
   <details class='spell-collapsible'>
     <summary class='collapse-spell'></summary>
+
     {% for pattern in page.patterns %}
       <canvas class='spell-viz' width='216' height='216' data-string='{{ pattern.signature }}' data-start='{{ pattern.startdir.name.lower() }}' data-per-world='{{ pattern.is_per_world }}'>
         Your browser does not support visualizing patterns. Pattern code: {{ pattern.signature }}

doc/templates/pages/PageWithText.html.jinja

@@ -1,5 +0,0 @@
-{% extends "pages/Page.html.jinja" %}
-
-{% block body %}
-  {{- page.text|hexdoc_block(true) -}}
-{% endblock %}

doc/templates/pages/PageWithTitle.html.jinja

@@ -1,17 +1,19 @@
-{% extends "pages/PageWithText.html.jinja" %}
+{% extends "pages/Page.html.jinja" %}
 {% import "macros.html.jinja" as macros %}
 
 {% block body %}
-  {%- if page.title is not none -%}
-    <h4{% block title_attrs %}{% endblock %}>{# we need title_attrs for PageWithPattern -#}
-      {{ page.title|hexdoc_block }}
-      {% if page_anchor_id is defined %} {# note: page_anchor_id is conditionally defined in Page #}
+  {% if page.title is not none %}
+    {# need title_attrs for LookupPatternPage -#}
+    <h4{% block title_attrs %}{% endblock %}>
+      {{ page.title|hexdoc_escape }}
+      {% if page_anchor_id is defined %} {# conditionally defined in Page #}
         {{ macros.permalink(page_anchor_id) }}
       {% endif %}
     </h4>
   {% endif %}
-  {# pretty sure this is the only good way to do this #}
-  {# and yes, this probably would have worked just fine in python too #}
-  {% set super_body = super() %}
-  {% block inner_body scoped %}{{ super_body }}{% endblock %}
+
+  {# within a separate block so we can control if the text goes before or after page-specific content #}
+  {% block inner_body %}
+    {{- page.text|hexdoc_block }}
+  {% endblock inner_body %}
 {% endblock body %}

doc/templates/pages/SpotlightPage.html.jinja

@@ -1,8 +1,6 @@
 {% extends "pages/PageWithTitle.html.jinja" %}
 
-{% block inner_body -%}
-  <h4 class='spotlight-title page-header'>
-    {{ page.item }}
-  </h4>
+{% block inner_body %}
+  <h4 class='spotlight-title page-header'>{{ page.item }}</h4>
   {{ super() }}
 {% endblock inner_body %}

doc/templates/tableofcontents.html.jinja

@@ -1,4 +1,6 @@
 {% import "macros.html.jinja" as macros %}
+
+{# section header #}
 <h2 id='table-of-contents' class='page-header'>
   Table of Contents
   <a href='javascript:void(0)' class='permalink toggle-link small' data-target='toc-category' title='Toggle all'>
@@ -6,16 +8,17 @@
   </a>
   {{ macros.permalink("table-of-contents") }}
 </h2>
+
+{# table of contents #}
 {% for category in book.categories.values() %}
   <details class='toc-category'>
-    <summary>
-      {{ macros.maybe_spoilered_link(category) }}
-    </summary>
+    {# category #}
+    <summary>{{ macros.maybe_spoilered_link(category) }}</summary>
+
+    {# list of entries in the category #}
     <ul>
       {% for entry in category.entries %}
-        <li>
-          {{ macros.maybe_spoilered_link(entry) }}
-        </li>
+        <li>{{ macros.maybe_spoilered_link(entry) }}</li>
       {% endfor %}
     </ul>
   </details>