From f234dee4563c943819cb1f3237cb761990215ad4 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 20 Jan 2025 22:45:42 +0000
Subject: [PATCH 1/4] Install matplotlib for opengraph preview images

---
 build_docs.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/build_docs.py b/build_docs.py
index 40384b8..f2954f6 100755
--- a/build_docs.py
+++ b/build_docs.py
@@ -789,6 +789,7 @@ def build_venv(self):
             [venv_path / "bin" / "python", "-m", "pip", "install", "--upgrade"]
             + ["--upgrade-strategy=eager"]
             + [self.theme]
+            + ["matplotlib>=3"] if self.includes_html else []  # opengraph previews
             + self.version.requirements,
             cwd=self.checkout / "Doc",
         )

From 73a5b04274988c199ee916f71d36d5691cd87251 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 20 Jan 2025 22:58:06 +0000
Subject: [PATCH 2/4] Define `create-social-cards` tag

---
 build_docs.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/build_docs.py b/build_docs.py
index f2954f6..3fa459a 100755
--- a/build_docs.py
+++ b/build_docs.py
@@ -745,6 +745,9 @@ def build(self):
         blurb = self.venv / "bin" / "blurb"
 
         if self.includes_html:
+            # For opengraph previews (requires matplotlib)
+            sphinxopts.append("-t create-social-cards")
+
             # Disable CPython switchers, we handle them now:
             run(
                 ["sed", "-i"]

From a62d744246c254a2207f555ca697b54b691832cf Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 20 Jan 2025 23:00:41 +0000
Subject: [PATCH 3/4] lint

---
 build_docs.py | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/build_docs.py b/build_docs.py
index 3fa459a..744b720 100755
--- a/build_docs.py
+++ b/build_docs.py
@@ -786,14 +786,17 @@ def build_venv(self):
         So we can reuse them from builds to builds, while they contain
         different Sphinx versions.
         """
+        requirements = [self.theme] + self.version.requirements
+        if self.includes_html:
+            # opengraph previews
+            requirements.append("matplotlib>=3")
+
         venv_path = self.build_root / ("venv-" + self.version.name)
         run([sys.executable, "-m", "venv", venv_path])
         run(
             [venv_path / "bin" / "python", "-m", "pip", "install", "--upgrade"]
             + ["--upgrade-strategy=eager"]
-            + [self.theme]
-            + ["matplotlib>=3"] if self.includes_html else []  # opengraph previews
-            + self.version.requirements,
+            + requirements,
             cwd=self.checkout / "Doc",
         )
         run([venv_path / "bin" / "python", "-m", "pip", "freeze", "--all"])

From e940d20deb7cec2d17283065a65efeb71be81cba Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Mon, 20 Jan 2025 23:13:17 +0000
Subject: [PATCH 4/4] Clarify comment

---
 build_docs.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/build_docs.py b/build_docs.py
index 744b720..a6b08bb 100755
--- a/build_docs.py
+++ b/build_docs.py
@@ -745,7 +745,8 @@ def build(self):
         blurb = self.venv / "bin" / "blurb"
 
         if self.includes_html:
-            # For opengraph previews (requires matplotlib)
+            # Define a tag to enable opengraph socialcards previews
+            # (used in Doc/conf.py and requires matplotlib)
             sphinxopts.append("-t create-social-cards")
 
             # Disable CPython switchers, we handle them now: