diff --git a/arcade/resources/__init__.py b/arcade/resources/__init__.py index dcbe32655..d805f3e46 100644 --- 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 ` 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 index ed819cb00..7dd716b75 100644 --- 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
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)