Use first image (after refactor) (#26)

* Use first image (after refactor)

Co-authored-by: tcmetzger <[email protected]>

* black

* fix first_image no uri edge case

* Use iana instead of wikipedia for mime types

* black

* Address comments

* black

Co-authored-by: tcmetzger <[email protected]>

Author: TheTripleV

README.md

@@ -13,7 +13,7 @@ Just add `sphinxext.opengraph` to your extensions list in your `conf.py`
 
 ```python
 extensions = [
-   sphinxext.opengraph,
+   "sphinxext.opengraph",
 ]
 ```
 ## Options
@@ -29,6 +29,8 @@ These values are placed in the conf.py of your sphinx project.
     * This is not required. Link to image to show.
 * `ogp_image_alt`
     * This is not required. Alt text for image. Defaults to using `ogp_site_name` or the document's title as alt text, if available. Set to `False` if you want to turn off alt text completely.
+* `ogp_use_first_image`
+    * This is not required. Set to True to use each page's first image, if available. If set to True but no image is found, Sphinx will use `ogp_image` instead.
 * `ogp_type`
     * This sets the ogp type attribute, for more information on the types available please take a look at https://ogp.me/#types. By default it is set to `website`, which should be fine for most use cases.
 * `ogp_custom_meta_tags`

sphinxext/opengraph/__init__.py

@@ -1,5 +1,6 @@
 from typing import Any, Dict
 from urllib.parse import urljoin
+from pathlib import Path
 
 import docutils.nodes as nodes
 from sphinx.application import Sphinx
@@ -9,6 +10,20 @@
 
 DEFAULT_DESCRIPTION_LENGTH = 200
 
+# A selection from https://www.iana.org/assignments/media-types/media-types.xhtml#image
+IMAGE_MIME_TYPES = {
+    "gif": "image/gif",
+    "apng": "image/apng",
+    "webp": "image/webp",
+    "jpeg": "image/jpeg",
+    "jpg": "image/jpeg",
+    "png": "image/png",
+    "bmp": "image/bmp",
+    "heic": "image/heic",
+    "heif": "image/heif",
+    "tiff": "image/tiff",
+}
+
 
 def make_tag(property: str, content: str) -> str:
     return f'<meta property="{property}" content="{content}" />\n  '
@@ -55,19 +70,30 @@ def get_tags(
     tags += make_tag("og:description", description)
 
     # image tag
-    # Get the image from the config
+    # Get basic values from config
     image_url = config["ogp_image"]
+    ogp_use_first_image = config["ogp_use_first_image"]
+    ogp_image_alt = config["ogp_image_alt"]
+
+    if ogp_use_first_image:
+        first_image = doctree.next_node(nodes.image)
+        if (
+            first_image
+            and Path(first_image.get("uri", "")).suffix[1:].lower() in IMAGE_MIME_TYPES
+        ):
+            image_url = first_image["uri"]
+            ogp_image_alt = first_image.get("alt", None)
+
     if image_url:
         tags += make_tag("og:image", image_url)
 
-    # Add image alt text (either provided by config or from site_name)
-    ogp_image_alt = config["ogp_image_alt"]
-    if isinstance(ogp_image_alt, str):
-        tags += make_tag("og:image:alt", ogp_image_alt)
-    elif ogp_image_alt and site_name:
-        tags += make_tag("og:image:alt", site_name)
-    elif ogp_image_alt and title:
-        tags += make_tag("og:image:alt", title)
+        # Add image alt text (either provided by config or from site_name)
+        if isinstance(ogp_image_alt, str):
+            tags += make_tag("og:image:alt", ogp_image_alt)
+        elif ogp_image_alt and site_name:
+            tags += make_tag("og:image:alt", site_name)
+        elif ogp_image_alt and title:
+            tags += make_tag("og:image:alt", title)
 
     # custom tags
     tags += "\n".join(config["ogp_custom_meta_tags"])
@@ -91,6 +117,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value("ogp_description_length", DEFAULT_DESCRIPTION_LENGTH, "html")
     app.add_config_value("ogp_image", None, "html")
     app.add_config_value("ogp_image_alt", True, "html")
+    app.add_config_value("ogp_use_first_image", False, "html")
     app.add_config_value("ogp_type", "website", "html")
     app.add_config_value("ogp_site_name", None, "html")
     app.add_config_value("ogp_custom_meta_tags", [], "html")

tests/roots/test-first-image-no-image/conf.py

@@ -0,0 +1,12 @@
+extensions = ["sphinxext.opengraph"]
+
+master_doc = "index"
+exclude_patterns = ["_build"]
+
+html_theme = "basic"
+
+ogp_site_name = "Example's Docs!"
+ogp_site_url = "http://example.org/"
+ogp_image = "http://example.org/image33.png"
+ogp_image_alt = "TEST"
+ogp_use_first_image = True

tests/roots/test-first-image-no-image/index.rst

@@ -0,0 +1 @@
+Title Only

tests/roots/test-first-image/conf.py

@@ -0,0 +1,12 @@
+extensions = ["sphinxext.opengraph"]
+
+master_doc = "index"
+exclude_patterns = ["_build"]
+
+html_theme = "basic"
+
+ogp_site_name = "Example's Docs!"
+ogp_site_url = "http://example.org/"
+ogp_image = "http://example.org/image33.png"
+ogp_image_alt = "TEST"
+ogp_use_first_image = True

tests/roots/test-first-image/index.rst

@@ -0,0 +1,2 @@
+.. image:: http://example.org/image2.png
+   :alt: Test image alt text

tests/test_options.py

@@ -54,6 +54,18 @@ def test_site_name(og_meta_tags):
     assert get_tag_content(og_meta_tags, "site_name") == "Example's Docs!"
 
 
+@pytest.mark.sphinx("html", testroot="first-image")
+def test_first_image(og_meta_tags):
+    assert get_tag_content(og_meta_tags, "image") == "http://example.org/image2.png"
+    assert get_tag_content(og_meta_tags, "image:alt") == "Test image alt text"
+
+
+@pytest.mark.sphinx("html", testroot="first-image-no-image")
+def test_first_image_no_image(og_meta_tags):
+    assert get_tag_content(og_meta_tags, "image") == "http://example.org/image33.png"
+    assert get_tag_content(og_meta_tags, "image:alt") == "TEST"
+
+
 @pytest.mark.sphinx("html", testroot="skip-admonitions")
 def test_skip_admonitions(og_meta_tags):
     assert get_tag_content(og_meta_tags, "description") == "This is text."