From 4933664e063dae670cd587743ead691195a2cbc2 Mon Sep 17 00:00:00 2001 From: Jon Mease Date: Sat, 7 Jan 2023 14:16:47 -0500 Subject: [PATCH] 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 | 3 -- CONTRIBUTING.md | 9 ++---- sphinxext/altairgallery.py | 31 +++++++++++++++++---- tests/examples_arguments_syntax/__init__.py | 7 +++++ tests/examples_methods_syntax/__init__.py | 5 ++++ 5 files changed, 41 insertions(+), 14 deletions(-) diff --git a/.github/workflows/docbuild.yml b/.github/workflows/docbuild.yml index 788deac15..18ac20a01 100644 --- a/.github/workflows/docbuild.yml +++ b/.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: | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 59de7e4f7..2e81ce75e 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/sphinxext/altairgallery.py b/sphinxext/altairgallery.py index 2b62dcba4..268868d74 100644 --- a/sphinxext/altairgallery.py +++ b/sphinxext/altairgallery.py @@ -5,6 +5,7 @@ import collections from operator import itemgetter import warnings +import shutil import jinja2 @@ -59,7 +60,15 @@ {% for example in group %} - + + {{ example.title }} {% endfor %} @@ -87,7 +96,14 @@
{% for example in examples %} - + {% endfor %}
@@ -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: diff --git a/tests/examples_arguments_syntax/__init__.py b/tests/examples_arguments_syntax/__init__.py index a9575575a..aa8f2abc4 100644 --- a/tests/examples_arguments_syntax/__init__.py +++ b/tests/examples_arguments_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_arguments_syntax(): """Iterate over the examples in this directory. @@ -7,6 +11,8 @@ def iter_examples_arguments_syntax(): 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 } diff --git a/tests/examples_methods_syntax/__init__.py b/tests/examples_methods_syntax/__init__.py index 2890d753f..5bb277ed3 100644 --- a/tests/examples_methods_syntax/__init__.py +++ b/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 }