docs: Use SVG thumbnail for emoji example and use VlConvert to build …

…docs on CI (#2809)

* Use svg thumbnail for isotype emoji example

This example is not supported by vl-convert's PNG export

* Use vl-convert engine to generate doc thumbnails in CI

* flake8

* Remove altair_saver instructions from README

* Remove selenium from docbuild.yml

* Extract SVG_EXAMPLES as global set with comment

* Add comment to the "Adding Examples" instructions

.github/workflows/docbuild.yml

@@ -19,10 +19,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install .[dev]
-        pip install "selenium<4.3.0"
-        pip install altair_saver
         pip install -r doc/requirements.txt
-        pip uninstall vl-convert-python --yes
         pip install git+https://github.com/altair-viz/altair_viewer.git
     - name: Run docbuild
       run: |

CONTRIBUTING.md

@@ -152,6 +152,9 @@ Some additional notes:
   included then it should be referenced by URL, such as `source =
   data.movies.url`. This is to ensure that Altair's automated test suite does
   not depend on availability of external HTTP resources.
+- If VlConvert does not support PNG export of the chart (e.g. in the case of emoji),
+  then add the name of the example to the `SVG_EXAMPLES` set in 
+  `tests/examples_arguments_syntax/__init__.py` and `tests/examples_methods_syntax/__init__.py`
 
 ### Building the Documentation Locally
 In addition to the development dependencies mentioned further above,
@@ -164,12 +167,6 @@ for details.
 pip install -r doc/requirements.txt
 ```
 
-If you want to build the documentation so it can be published on the [official Altair website](https://altair-viz.github.io), you need to
-additionally install [altair_saver](https://github.com/altair-viz/altair_saver/) and uninstall [vl-convert-python](https://github.com/vega/vl-convert/tree/main/vl-convert-python).
-These packages are used to generate PNG thumbnails for the example gallery. If both are installed, `vl-convert-python` is used by default.
-The reason for this is that `vl-convert-python` cannot create a thumbnail for the `isotype_emoji.py` example,
-which is fine for normal contributions but not when creating a new version of the official documentation.
-
 Once you have all the dependencies, you can build the documentation 
 using various commands defined in the Makefile. 
 From the `doc` folder, you can use `make help` to see all of the available commands

sphinxext/altairgallery.py

@@ -5,6 +5,7 @@
 import collections
 from operator import itemgetter
 import warnings
+import shutil
 
 import jinja2
 
@@ -59,7 +60,15 @@
    <span class="gallery">
    {% for example in group %}
    <a class="imagegroup" href="{{ example.name }}.html">
-     <span class="image" alt="{{ example.title }}" style="background-image: url(..{{ image_dir }}/{{ example.name }}-thumb.png);"></span>
+   <span
+        class="image" alt="{{ example.title }}"
+{% if example['use_svg'] %}
+        style="background-image: url(..{{ image_dir }}/{{ example.name }}-thumb.svg);"
+{% else %}
+        style="background-image: url(..{{ image_dir }}/{{ example.name }}-thumb.png);"
+{% endif %}
+    ></span>
+
      <span class="image-title">{{ example.title }}</span>
    </a>
    {% endfor %}
@@ -87,7 +96,14 @@
     <div id="showcase">
       <div class="examples">
       {% for example in examples %}
-        <a class="preview" href="{{ gallery_dir }}/{{ example.name }}.html" style="background-image: url(.{{ image_dir }}/{{ example.name }}-thumb.png)"></a>
+      <a
+        class="preview" href="{{ gallery_dir }}/{{ example.name }}.html"
+{% if example['use_svg'] %}
+        style="background-image: url(.{{ image_dir }}/{{ example.name }}-thumb.svg)"
+{% else %}
+        style="background-image: url(.{{ image_dir }}/{{ example.name }}-thumb.png)"
+{% endif %}
+      ></a>
       {% endfor %}
       </div>
     </div>
@@ -130,7 +146,7 @@ def save_example_pngs(examples, image_dir, make_thumbnails=True):
         hashes = {}
 
     for example in examples:
-        filename = example["name"] + ".png"
+        filename = example["name"] + (".svg" if example["use_svg"] else ".png")
         image_file = os.path.join(image_dir, filename)
 
         example_hash = hashlib.md5(example["code"].encode()).hexdigest()
@@ -154,8 +170,13 @@ def save_example_pngs(examples, image_dir, make_thumbnails=True):
 
         if make_thumbnails:
             params = example.get("galleryParameters", {})
-            thumb_file = os.path.join(image_dir, example["name"] + "-thumb.png")
-            create_thumbnail(image_file, thumb_file, **params)
+            if example["use_svg"]:
+                # Thumbnail for SVG is identical to original image
+                thumb_file = os.path.join(image_dir, example["name"] + "-thumb.svg")
+                shutil.copyfile(image_file, thumb_file)
+            else:
+                thumb_file = os.path.join(image_dir, example["name"] + "-thumb.png")
+                create_thumbnail(image_file, thumb_file, **params)
 
     # Save hashes so we know whether we need to re-generate plots
     with open(hash_file, "w") as f:

tests/examples_arguments_syntax/__init__.py

@@ -1,12 +1,18 @@
 import os
 
+# Set of the names of examples that should have SVG static images.
+# This is for examples that VlConvert's PNG export does not support.
+SVG_EXAMPLES = {"isotype_emoji"}
+
 
 def iter_examples_arguments_syntax():
     """Iterate over the examples in this directory.
 
     Each item is a dict with the following keys:
     - "name" : the unique name of the example
     - "filename" : the full file path to the example
+    - "use_svg": Flag indicating whether the static image for the
+        example should be an SVG instead of a PNG
     """
     examples_arguments_syntax_dir = os.path.abspath(os.path.dirname(__file__))
     for filename in os.listdir(examples_arguments_syntax_dir):
@@ -16,4 +22,5 @@ def iter_examples_arguments_syntax():
         yield {
             "name": name,
             "filename": os.path.join(examples_arguments_syntax_dir, filename),
+            "use_svg": name in SVG_EXAMPLES
         }

tests/examples_methods_syntax/__init__.py

@@ -1,5 +1,9 @@
 import os
 
+# Set of the names of examples that should have SVG static images.
+# This is for examples that VlConvert's PNG export does not support.
+SVG_EXAMPLES = {"isotype_emoji"}
+
 
 def iter_examples_methods_syntax():
     """Iterate over the examples in this directory.
@@ -16,4 +20,5 @@ def iter_examples_methods_syntax():
         yield {
             "name": name,
             "filename": os.path.join(examples_methods_syntax_dir, filename),
+            "use_svg": name in SVG_EXAMPLES
         }