DOC: Generate the list of supported fonts dynamically from codes (#3406)

Co-authored-by: Yvonne Fröhlich <[email protected]>

Author: seisman

doc/_static/style.css

@@ -203,3 +203,19 @@ a.copybtn {
 .sphx-glr-single-img {
     max-width: 80%!important;
 }
+
+/*
+ * Styles for aligning table cells.
+ * https://myst-parser.readthedocs.io/en/latest/syntax/tables.html#markdown-syntax
+ */
+th.text-left, td.text-left {
+    text-align: left !important;
+}
+
+th.text-center, td.text-center {
+    text-align: center !important;
+}
+
+th.text-right, td.text-right {
+    text-align: right !important;
+}

doc/conf.py

@@ -61,6 +61,9 @@
     "requires": requirements,
 }
 
+# MyST-NB configurations.
+# Reference: https://myst-nb.readthedocs.io/en/latest/configuration.html
+nb_render_markdown_format = "myst"  # The format to use for text/markdown rendering
 
 # Make the list of returns arguments and attributes render the same as the
 # parameters list

doc/techref/fonts.md

@@ -1,3 +1,7 @@
+---
+file_format: mystnb
+---
+
 # Supported Fonts
 
 PyGMT supports the 35 standard PostScript fonts. The table below lists them with their
@@ -7,25 +11,104 @@ either `"Helvetica"` or `"0"`. For the special fonts "Symbol" (**12**) and
 "ZapfDingbats" (**34**), see the {doc}`/techref/encodings` for the character set.
 The image below the table shows a visual sample for each font.
 
-| Font No. | Font Name              | Font No. | Font Name                    |
-|----------|------------------------|----------|------------------------------|
-| 0        | Helvetica              | 17       | Bookman-Demi                 |
-| 1        | Helvetica-Bold         | 18       | Bookman-DemiItalic           |
-| 2        | Helvetica-Oblique      | 19       | Bookman-Light                |
-| 3        | Helvetica-BoldOblique  | 20       | Bookman-LightItalic          |
-| 4        | Times-Roman            | 21       | Helvetica-Narrow             |
-| 5        | Times-Bold             | 22       | Helvetica-Narrow-Bold        |
-| 6        | Times-Italic           | 23       | Helvetica-Narrow-Oblique     |
-| 7        | Times-BoldItalic       | 24       | Helvetica-Narrow-BoldOblique |
-| 8        | Courier                | 25       | NewCenturySchlbk-Roman       |
-| 9        | Courier-Bold           | 26       | NewCenturySchlbk-Italic      |
-| 10       | Courier-Oblique        | 27       | NewCenturySchlbk-Bold        |
-| 11       | Courier-BoldOblique    | 28       | NewCenturySchlbk-BoldItalic  |
-| 12       | Symbol                 | 29       | Palatino-Roman               |
-| 13       | AvantGarde-Book        | 30       | Palatino-Italic              |
-| 14       | AvantGarde-BookOblique | 31       | Palatino-Bold                |
-| 15       | AvantGarde-Demi        | 32       | Palatino-BoldItalic          |
-| 16       | AvantGarde-DemiOblique | 33       | ZapfChancery-MediumItalic    |
-|          |                        | 34       | ZapfDingbats                 |
-
-![Standard PostScript Fonts](https://docs.generic-mapping-tools.org/dev/_images/GMT_App_G.png){width="67.5%"}
+```{code-cell}
+---
+tags: [remove-input]
+---
+from IPython.display import display, Markdown
+
+fonts = [
+    "Helvetica",
+    "Helvetica-Bold",
+    "Helvetica-Oblique",
+    "Helvetica-BoldOblique",
+    "Times-Roman",
+    "Times-Bold",
+    "Times-Italic",
+    "Times-BoldItalic",
+    "Courier",
+    "Courier-Bold",
+    "Courier-Oblique",
+    "Courier-BoldOblique",
+    "Symbol",
+    "AvantGarde-Book",
+    "AvantGarde-BookOblique",
+    "AvantGarde-Demi",
+    "AvantGarde-DemiOblique",
+    "Bookman-Demi",
+    "Bookman-DemiItalic",
+    "Bookman-Light",
+    "Bookman-LightItalic",
+    "Helvetica-Narrow",
+    "Helvetica-Narrow-Bold",
+    "Helvetica-Narrow-Oblique",
+    "Helvetica-Narrow-BoldOblique",
+    "NewCenturySchlbk-Roman",
+    "NewCenturySchlbk-Italic",
+    "NewCenturySchlbk-Bold",
+    "NewCenturySchlbk-BoldItalic",
+    "Palatino-Roman",
+    "Palatino-Italic",
+    "Palatino-Bold",
+    "Palatino-BoldItalic",
+    "ZapfChancery-MediumItalic",
+    "ZapfDingbats",
+]
+
+text = "| Font No. | Font Name | Font No. | Font Name |\n"
+text += "|:---:|:---|:---:|:---|\n"
+for i in range(17):
+    j = i + 17
+    text += f"| {i} | {fonts[i]} | {j} | {fonts[j]} |\n"
+text += f"| | | 34 | {fonts[34]} |\n"
+
+display(Markdown(text))
+```
+
+```{code-cell}
+---
+tags: [remove-input]
+---
+"""
+Script to generate visual samples of the fonts.
+"""
+import pygmt
+
+x1, x2, dx = 0, 7, 0.75
+
+fig = pygmt.Figure()
+# Draw the table
+fig.basemap(region=[-0.5, 14, -1.5, 18], projection="X14c/-10c", frame=0)
+fig.plot(x=[-0.5, 14], y=[-0.5, -0.5])
+for x in (0.5, 6.5, 7.5):
+    fig.plot(x=[x, x], y=[-1.5, 18])
+# Table header
+fig.text(
+    x=[x1, x1 + dx, x2, x2 + dx],
+    y=[-1] * 4,
+    text=["#", "Font Name"] * 2,
+    justify=["MC", "ML"] * 2,
+    font="Helvetica-Bold",
+)
+# Fonts
+for i, font in enumerate(fonts):
+    x0 = x1 if i < 17 else x2
+    y0 = i % 17
+    font_no, font_name = i, font
+
+    # Deal with special cases
+    if font in ["Symbol", "ZapfDingbats"]:
+        font_name = f"{font} @%0%({font})@%%"
+    if font == "ZapfDingbats":
+        font_no = "@%0%34@%%"
+        y0 = 17
+
+    fig.text(
+        x=[x0, x0 + dx],
+        y=[y0] * 2,
+        text=[font_no, font_name],
+        justify=["MC", "ML"],
+        font=font,
+    )
+fig.show(width=600)
+```