Add exception for SVG images (#97)

* Add exception for SVG images

* posix to str

* Mini svg as well

* Document image svg

* Lower

* Better social image path validation

* Fix test

* Black

* Check for None

Author: choldgraf

docs/source/socialcards.md

@@ -23,13 +23,31 @@ ogp_social_cards = {
 }
 ```
 
+## Update the top-right image
+
+By default the top-right image will use the image specified by `html_logo` if it exists.
+To update it, specify another path in the **`image`** key like so:
+
+```{code-block} python
+:caption: conf.py
+
+ogp_social_cards = {
+    "image": "path/to/image.png",
+}
+```
+
+```{admonition} The image cannot be an SVG
+:class: warning
+
+Matplotlib does not support easy plotting of SVG images, so ensure that your image is a PNG or JPEG file, not SVG.
+```
+
 ## Customize the card
 
 There are several customization options to change the text and look of the social media preview card.
 Below is a summary of these options.
 
 - **`site_url`**: Set a custom site URL.
-- **`image`**: Over-ride the top-right image (by default, `html_logo` is used).
 - **`line_color`**: Color of the border line at the bottom of the card, in hex format.
 % TODO: add an over-ride for each part of the card.
 

sphinxext/opengraph/socialcards.py

@@ -4,10 +4,11 @@
 import matplotlib
 from matplotlib import pyplot as plt
 import matplotlib.image as mpimg
+from sphinx.util import logging
 
 matplotlib.use("agg")
 
-
+LOGGER = logging.getLogger(__name__)
 HERE = Path(__file__).parent
 MAX_CHAR_PAGE_TITLE = 75
 MAX_CHAR_DESCRIPTION = 175
@@ -91,6 +92,22 @@ def create_social_card(
             Path(__file__).parent / "_static/sphinx-logo-shadow.png"
         )
 
+    # Validation on the images
+    for img in ["image_mini", "image"]:
+        impath = kwargs_fig.get(img)
+        if not impath:
+            continue
+
+        # If image is an SVG replace it with None
+        if impath.suffix.lower() == ".svg":
+            LOGGER.warn(f"[Social card] {img} cannot be an SVG image, skipping...")
+            kwargs_fig[img] = None
+
+        # If image doesn't exist, throw a warning and replace with none
+        if not impath.exists():
+            LOGGER.warn(f"[Social card]: {img} file doesn't exist, skipping...")
+            kwargs_fig[img] = None
+
     # These are passed directly from the user configuration to our plotting function
     pass_through_config = ["text_color", "line_color", "background_color", "font"]
     for config in pass_through_config:
@@ -265,12 +282,12 @@ def create_social_card_objects(
             c=site_url_color,
         )
 
-    if image_mini:
+    if isinstance(image_mini, Path):
         img = mpimg.imread(image_mini)
         axim_mini.imshow(img)
 
     # Put the logo in the top right if it exists
-    if image:
+    if isinstance(image, Path):
         img = mpimg.imread(image)
         yw, xw = img.shape[:2]
 

tests/roots/test-social-cards-svg/conf.py

@@ -0,0 +1,12 @@
+extensions = ["sphinxext.opengraph"]
+
+master_doc = "index"
+exclude_patterns = ["_build"]
+
+html_theme = "basic"
+ogp_site_url = "http://example.org/en/latest/"
+
+# The image is an SVG, and so it should not be included in the social cards
+ogp_social_cards = {
+    "image": "foo.svg",
+}

tests/roots/test-social-cards-svg/index.rst

@@ -0,0 +1 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse at lorem ornare, fringilla massa nec, venenatis mi. Donec erat sapien, tincidunt nec rhoncus nec, scelerisque id diam. Orci varius natoque penatibus et magnis dis parturient mauris.

tests/test_options.py

@@ -87,6 +87,12 @@ def test_local_image(og_meta_tags):
     )
 
 
+@pytest.mark.sphinx("html", testroot="social-cards-svg")
+def test_social_cards_svg(app: Sphinx, og_meta_tags):
+    """If the social cards image is an SVG, it should not be in the social card."""
+    assert app.statuscode == 0
+
+
 @pytest.mark.sphinx("html", testroot="image")
 def test_image_alt(og_meta_tags):
     assert get_tag_content(og_meta_tags, "image:alt") == "Example's Docs!"