feat: allow specifying a custom font for the card text (#110)

* feat: allow specifying a custom font for the card text * docs: write "Customize the text font" section * fix: apply black
wpilibsuite · Oct 27, 2023 · fd959a7 · fd959a7
1 parent 457e75d
commit fd959a7
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 10 deletions.
diff --git a/docs/source/socialcards.md b/docs/source/socialcards.md
@@ -7,6 +7,7 @@ See [the opengraph.xyz website](https://www.opengraph.xyz/) for a way to preview
 Here's an example of what the card for this page looks like:
 
 % This is auto-generated at build time
+
 ```{image} ../tmp//num_0.png
 :width: 500
 ```
@@ -42,14 +43,33 @@ ogp_social_cards = {
 Matplotlib does not support easy plotting of SVG images, so ensure that your image is a PNG or JPEG file, not SVG.
 ```
 
+## Customize the text font
+
+By default, the Roboto Flex font is used to render the card text.
+
+You can specify the other font name via ``font`` key:
+
+```{code-block} python
+:caption: conf.py
+
+ogp_social_cards = {
+    "font": "Noto Sans CJK JP",
+}
+```
+
+You might need to install an additional font package on your environment. Also, note that the font name needs to be
+discoverable by Matplotlib FontManager.
+See [Matplotlib documentation](https://matplotlib.org/stable/tutorials/text/text_props.html#default-font)
+for the information about FontManager.
+
 ## 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.
 - **`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.
+  % TODO: add an over-ride for each part of the card.
 
 ## Example social cards
 

diff --git a/sphinxext/opengraph/socialcards.py b/sphinxext/opengraph/socialcards.py
@@ -178,16 +178,17 @@ def create_social_card_objects(
     site_url_color="#2f363d",
     background_color="white",
     line_color="#5A626B",
-    font="Roboto",
+    font=None,
 ):
     """Create the Matplotlib objects for the first time."""
-    # Load the Roboto font
-    # TODO: Currently the `font` parameter above does nothing
-    #   Should instead make it possible to load remote fonts or local fonts
-    #   if a user specifies.
-    path_font = Path(__file__).parent / "_static/Roboto-flex.ttf"
-    font = matplotlib.font_manager.FontEntry(fname=str(path_font), name="Roboto")
-    matplotlib.font_manager.fontManager.ttflist.append(font)
+    # If no font specified, load the Roboto Flex font as a fallback
+    if font is None:
+        path_font = Path(__file__).parent / "_static/Roboto-flex.ttf"
+        roboto_font = matplotlib.font_manager.FontEntry(
+            fname=str(path_font), name="Roboto"
+        )
+        matplotlib.font_manager.fontManager.ttflist.append(roboto_font)
+        font = roboto_font.name
 
     # Because Matplotlib doesn't let you specify figures in pixels, only inches
     # This `multiple` results in a scale of about 1146px by 600px
@@ -214,7 +215,7 @@ def create_social_card_objects(
 
     # Axes configuration
     left_margin = 0.05
-    with plt.rc_context({"font.family": font.name}):
+    with plt.rc_context({"font.family": font}):
         # Site title
         # Smaller font, just above page title
         site_title_y_offset = 0.87