Add cross-refs and some temp tables

pythonarcade · Jan 14, 2025 · fda3731 · fda3731
1 parent b7e775a
commit fda3731
Show file tree

Hide file tree

Showing 2 changed files with 69 additions and 20 deletions.
diff --git a/arcade/resources/__init__.py b/arcade/resources/__init__.py
@@ -221,19 +221,34 @@ def list_built_in_assets(
 def load_kenney_fonts() -> None:
     """Loads all the Kenney.nl fonts bundled with Arcade.
 
-    Currently, this includes the following fonts::
-
-        Kenney_Blocks.ttf          - Kenney Blocks
-        Kenney_Future.ttf          - Kenney Future
-        Kenney_Future_Narrow.ttf   - Kenney Future Narrow
-        Kenney_High.ttf            - Kenney High
-        Kenney_High_Square.ttf     - Kenney High Square
-        Kenney_Mini.ttf            - Kenney Mini
-        Kenney_Mini_Square.ttf     - Kenney Mini Square
-        Kenney_Pixel.ttf           - Kenney Pixel
-        Kenney_Pixel_Square.ttf    - Kenney Pixel Square
-        Kenney_Rocket.ttf          - Kenney Rocket
-        Kenney_Rocket_Square.ttf   - Kenney Rocket Square
+    .. tip:: This function is best for prototyping and experimenting!
+
+         For best performance, you may want to switch to
+         :py:class:`arcade.load_font` before release.
+
+    Please see :ref:`resources-fonts-kenney` for previews and
+    license information. The filename to load and ``font_name`` to use
+    when drawing text are summarized below:
+
+    .. might swap to this style for the resources listing once I figure out how to
+    .. cleanly modify the file to use it.
+
+    =========================================  =========================================================================
+    ``font_name`` for :py:class:`arcade.Text`  :ref:`Resource handle <resource_handles>` for :py:func:`arcade.load_font`
+    =========================================  =========================================================================
+    ``"Kenney Blocks"``                        ``:resources:fonts/ttf/Kenney/Kenney_Blocks.ttf``
+    ``"Kenney Future"``                        ``:resources:fonts/ttf/Kenney/Kenney_Future.ttf``
+    ``"Kenney Future Narrow"``                 ``:resources:fonts/ttf/Kenney/Kenney_Future_Narrow.ttf``
+    ``"Kenney High"``                          ``:resources:fonts/ttf/Kenney/Kenney_High.ttf``
+    ``"Kenney High Square"``                   ``:resources:fonts/ttf/Kenney/Kenney_High_Square.ttf``
+    ``"Kenney Mini"``                          ``:resources:fonts/ttf/Kenney/Kenney_Mini.ttf``
+    ``"Kenney Mini Square"``                   ``:resources:fonts/ttf/Kenney/Kenney_Mini_Square.ttf``
+    ``"Kenney Pixel"``                         ``:resources:fonts/ttf/Kenney/Kenney_Pixel.ttf``
+    ``"Kenney Pixel Square"``                  ``:resources:fonts/ttf/Kenney/Kenney_Pixel_Square.ttf``
+    ``"Kenney Rocket"``                        ``:resources:fonts/ttf/Kenney/Kenney_Rocket.ttf``
+    ``"Kenney Rocket Square"``                 ``:resources:fonts/ttf/Kenney/Kenney_Rocket_Square.ttf``
+    =========================================  =========================================================================
+
     """
     from arcade.text import load_font
 
@@ -251,10 +266,32 @@ def load_kenney_fonts() -> None:
 
 
 def load_liberation_fonts() -> None:
-    """Loads generic versions of Arial, Courier, and Times New Roman.
+    """Loads all styles for generic Arial, Courier, and Times New Roman replacements.
+
+    .. tip:: This function is best for prototyping and experimenting!
+
+             For best performance, you may want to switch to
+             :py:class:`arcade.load_font` before release.
+
+    The Liberation fonts are proven, permissively-licensed fonts.[
+    For previews and additional information, please see
+    :ref:`resources-fonts-liberation`.
+
+    .. list-table:: ``font_name`` values for :py:class:`arcade.Text`
+       :header-rows: 1
+
+       * - Proprietary Font(s)
+         - Liberation Replacemetn
+
+       * - ``"Courier"``
+         - ``"Liberation Mono"``
+
+       * - ``"Times New Roman"``, ``"Times"``
+         - ``"Liberation Serif"``
+
+       * - ``"Arial"``
+         - ``"Liberation Sans"``
 
-    The Liberation font family is a permissively-licensed set of built-ins
-    which should be layout-compatible with popular fonts.
     """
     from arcade.text import load_font
 

diff --git a/util/create_resources_listing.py b/util/create_resources_listing.py
@@ -116,6 +116,11 @@ def create_resource_path(
 KENNEY_TTFS = "Kenney TTFs"
 LIBERATION_TTFS = "Liberation TTFs"
 
+PREFIX_REF_TARGET = {
+    KENNEY_TTFS: "resources-fonts-kenney",
+    LIBERATION_TTFS: "resources-fonts-liberation"
+}
+
 # pending: post-3.0 cleanup  # unstructured kludge
 REPLACE_TITLE_WORDS = {
     "Kenney": KENNEY_TTFS,
@@ -267,6 +272,9 @@ def _debug_print_files() -> None:  # pending: post-3.0 cleanup
 
                     # print("!!!", heading_level, part, as_tup)
 
+                    if ref_target := PREFIX_REF_TARGET.get(part, None):
+                        out.write(f".. _{ref_target}:\n")
+
                     do_heading(out, heading_level, part)
                     visited_headings.add(as_tup)
 
@@ -297,11 +305,15 @@ def _debug_print_files() -> None:  # pending: post-3.0 cleanup
                         # Put the text *after* the CSS, or add <br> via .. raw:: html blocks
                         # since the CSS may be broken.
                         "\n"
-                        "Arcade also includes the Liberation font family. This trio of fonts is designed as\n"
-                        "generic, drop-in replacements for Times New Roman, Arial, and Courier.\n"
+                        "Arcade also includes the Liberation font family. This trio is designed and\n"
+                        "licensed specifically to be a portable, drop-in set of substitutes for Times, Arial,\n"
+                        "and Courier fonts. It uses the proven, commercial-friendly `SIL Open Font License`_.\n"
+                        "\n"
+                        "To use these fonts, you may use either approach:\n"
+                        "\n"
+                        "* load files for specific variants via :py:func:`arcade.load_font`\n"
+                        "* load all variants at once with :py:func:`arcade.resources.load_liberation_fonts`.\n"
                         "\n"
-                        "The Liberation font family uses the proven, commercial-friendly\n"
-                        "`SIL Open Font License`_ widely accepted within games and design spaces.\n"
                     )
 
             n_cols = get_header_num_cols(raw_resource_handle, num_files)