Improve the structure of gallery examples (#1223)

source/_extensions/templatebridge.py

@@ -0,0 +1,26 @@
+"""
+Add custom filters to the Jinja2 environment.
+"""
+import hashlib
+
+from sphinx.jinja2glue import BuiltinTemplateLoader
+
+
+def _filemd5(file):
+    """
+    Return the MD5 hash of the file contents.
+    """
+    with open(file, "r") as fp:
+        data = fp.read()
+        return hashlib.md5(data.encode()).hexdigest()
+
+
+class MyTemplateBridge(BuiltinTemplateLoader):
+    """
+    Inherit from the default template bridge and add custom filters.
+    """
+
+    def init(self, builder, template_name):
+        super().init(builder, template_name)
+        # Add custom filters
+        self.environment.filters["filemd5"] = _filemd5

source/_templates/gallery.tmpl

@@ -6,12 +6,18 @@
 
 .. grid:: 2 3 3 4
     {% for fig in group["gallery"] %}
-    {% if fig["image"].startswith("http") %}  {# absolute URL for external images #}
-        {% set image = fig["image"] %}
-        {% set link, link_type = "/" + fig["target"], "doc" %}
-    {% else %}  {# internal images #}
-        {% set image = config.html_context["siteurl"] + "/_images/" + fig["image"] + ".png" %}
-        {% set link, link_type = "gmtplot-" + fig["image"], "ref" %}
+    {% if fig["script"] is defined %}
+        {% set md5value = fig["script"] | filemd5 %}
+        {% set image = config.html_context["siteurl"] + "/_images/" + md5value + ".png" %}
+        {% set link, link_type = "gmtplot-" + md5value, "ref" %}
+    {% else %}
+        {% if fig["image"].startswith("http") %}  {# absolute URL for external images #}
+            {% set image = fig["image"] %}
+            {% set link, link_type = "/" + fig["target"], "doc" %}
+        {% else %}  {# internal images #}
+            {% set image = config.html_context["siteurl"] + "/_images/" + fig["image"] + ".png" %}
+            {% set link, link_type = "gmtplot-" + fig["image"], "ref" %}
+        {% endif %}
     {% endif %}
     .. grid-item-card::
         :margin: 0 2 0 0

source/conf.py

@@ -58,6 +58,8 @@
     "gmtplot",
     "sphinxcontrib.datatemplates",
 ]
+# use custom templater bridge defined in _extensions/templatebridge.py
+template_bridge = "templatebridge.MyTemplateBridge"
 #mathjax_path = "https://cdn.bootcss.com/mathjax/2.7.7/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
 
 # Set smartquotes_action to "qe" to disable Smart Quotes transform of -- and ---

source/gallery/gallery.yaml

@@ -1,7 +1,7 @@
 ---
 title: 底图
 gallery:
-  - image: d44026c69907320e8680c507fffc6066
+  - script: conf/map_frame_type.sh
     title: MAP_FRAME_TYPE 控制底图边框类型
     target: conf/map/
   - image: d6a56a56fddb4bb54d57466b9d1e45c3