via .. raw:: html blocks +.. since the CSS may be broken. + +Arcade also includes the Liberation font family. This trio is designed and +licensed specifically to be a portable, drop-in set of substitutes for Times, Arial, +and Courier fonts. It uses the proven, commercial-friendly `SIL Open Font License`_. + +To use these fonts, you may use either approach: + +* load files for specific variants via :py:func:`arcade.load_font` +* load all variants at once with :py:func:`arcade.resources.load_liberation_fonts`. diff --git a/doc/_includes/resources_Top-Level_Resources.rst b/doc/_includes/resources_Top-Level_Resources.rst new file mode 100644 index 000000000..b69278445 --- /dev/null +++ b/doc/_includes/resources_Top-Level_Resources.rst @@ -0,0 +1,8 @@ +This logo of the snake doubles as a quick way to test Arcade's resource handles. + +#. Mouse over the copy button (|Example Copy Button|) below +#. It should change color to indicate you've hovered +#. Click to copy + +Paste in your favorite text editor! + diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css index 3178585f3..f633e7e9e 100644 --- a/doc/_static/css/custom.css +++ b/doc/_static/css/custom.css @@ -214,18 +214,120 @@ table.dataTable.display tbody tr.even > .sorting_1 { background-repeat: repeat; } + +/*Test*/ table.resource-table { empty-cells: hide; + white-space: normal; /* table behavior for CSS styling? maybe dupe of below. */ } + /* Make the resource page's table cell contents look neat */ -table.resource-table td { + +/* copy button doesn't need so much margin in here */ +.resource-table div.highlight-python { + margin-bottom: 0; +} + +/* Only center the contents of tiles which have images in them + * NOTE: The * instead of table alloes for non-table resource tiles + */ +*.resource-table td:has(.resource-thumb) { text-align: center; } -table.resource-table td > img { +.resource-table, +.resource-table table + { + width: 100%; + max-width: 100%; +} +.wy-table-responsive table :is(th, td) { white-space: normal; } +/* Prevent huge copyable areas for .. code:: boxes using sphinx-copybutton */ +.resource-table div.highlight > pre { + padding: 8px; +} + +table.resource-table td > .resource-thumb { display: inline-block; +} +table.resource-table td > img.resource-thumb { /* Maximum 20% of the smallest display dimension */ max-width: min(20vw, 20vh); } +table.resource-table td > .resource-thumb.file-icon { + width: 128px; + height: 128px; + max-width: 128px; + max-height: 128px; +} + + +.resource-handle { + display: inline-block; + border-radius: 0.4em; + border: 1px solid rgb(0, 0, 0, 0); + width: fit-content !important; +} +.resource-handle:has(button.arcade-ezcopy:hover) { + border-color: #54c079; + color: #54c079; +} +.resource-table .caption-text > .literal, +.resource-handle > .literal { + font-style: normal; + height: 1.5em; + min-height: 1.5em; + border-radius: 0.4em; + border: 1px solid #1b1f2426; + vertical-align: middle; + /* Not clear why this doesn't work for the .caption-text */ + font-size: 1em !important; +} + + +/* Imitate sphinx-copybutton style */ +.arcade-ezcopy { + width: 1.5em; + height: 1.5em; + min-width: 1.5em; + min-height: 1.5em; + padding: 0; + + /* Imitate sphinx-copybutton minus styling spacing issues */ + border-radius: 0.4em 0.4em 0.4em 0.4em; + border: 1px solid #1b1f2426; + + border-left: 0; + + color: #57606a; + background-color: #f6f8fa; + +} +/* Hide left border on items which haven adjacent copy button + + CAVEAT: This won't currently work with right-to-left layout modes! + + This is because of the following assume left-to-right: + + 1. The + here assumes the button element's next in the DOM order + 2. The right border of the box gets switched off + */ +.resource-table * > .literal:has(+ button.arcade-ezcopy) { + border-radius: 0.4em 0 0 0.4em !important; +} +.resource-table .literal + button.arcade-ezcopy { + border-radius: 0 0.4em 0.4em 0 !important; +} + + + +.arcade-ezcopy > img { + margin: 0; + width: 100%; + height: 100%; +} +.arcade-ezcopy:hover { + background-color: #54c079; +} table.colorTable { border-width: 1px; diff --git a/doc/_static/filetiles/state-error.png b/doc/_static/filetiles/state-error.png new file mode 100644 index 000000000..4084bdd1a Binary files /dev/null and b/doc/_static/filetiles/state-error.png differ diff --git a/doc/_static/filetiles/type-glsl.png b/doc/_static/filetiles/type-glsl.png new file mode 100644 index 000000000..81589c995 Binary files /dev/null and b/doc/_static/filetiles/type-glsl.png differ diff --git a/doc/_static/filetiles/type-json.png b/doc/_static/filetiles/type-json.png new file mode 100644 index 000000000..cea40baf4 Binary files /dev/null and b/doc/_static/filetiles/type-json.png differ diff --git a/doc/_static/filetiles/type-unknown.png b/doc/_static/filetiles/type-unknown.png new file mode 100644 index 000000000..259d50f4f Binary files /dev/null and b/doc/_static/filetiles/type-unknown.png differ diff --git a/doc/_static/js/custom.js b/doc/_static/js/custom.js index 5f2b3672d..30e450fb2 100644 --- a/doc/_static/js/custom.js +++ b/doc/_static/js/custom.js @@ -55,13 +55,14 @@ function handleSidebarHeaderToggle() { registerOnScrollEvent(mediaQuery); } } - - /** * Load all custom code only once the DOM document has fully loaded. * * Notice that jQuery is already available in this file. */ $(document).ready(() => { - handleSidebarHeaderToggle() + handleSidebarHeaderToggle(); + // Re-use the base ClipboardJS provided by sphinx-copybutton + // .doc-ui-example-dummy marks a button as a training dummy on the resources page and elsewhere + document.ezcopy = new ClipboardJS('.arcade-ezcopy:not(.doc-ui-example-dummy'); }); diff --git a/doc/api_docs/images/tiled_icon_digi_pls_replace.png b/doc/api_docs/images/tiled_icon_digi_pls_replace.png new file mode 100644 index 000000000..18ac05b9d Binary files /dev/null and b/doc/api_docs/images/tiled_icon_digi_pls_replace.png differ diff --git a/doc/conf.py b/doc/conf.py index e576ade07..11df9852e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -14,6 +14,10 @@ import sphinx.transforms import sys +from docutils import nodes +from docutils.nodes import literal +from sphinx.util.docutils import SphinxRole + # As of pyglet==2.1.dev7, this is no longer set in pyglet/__init__.py # because Jupyter / IPython always load Sphinx into sys.modules. See # the following for more info: @@ -166,7 +170,7 @@ def run_util(filename, run_name="__main__", init_globals=None): # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = [ - "links.rst", + "_includes/*", "substitutions.rst", "_archive/*", ] @@ -247,15 +251,22 @@ def run_util(filename, run_name="__main__", init_globals=None): 'pymunk': ('https://www.pymunk.org/en/latest/', None), } - # These will be joined as one block and prepended to every source file. # Substitutions for |version| and |release| are predefined by Sphinx. PROLOG_PARTS = [ #".. include:: /links.rst", ".. |pyglet Player| replace:: pyglet :py:class:`~pyglet.media.player.Player`", - ".. _Arcade's License File on GitHub: {FMT_URL_REF_BASE}/license.rst" + ".. _Arcade's License File on GitHub: {FMT_URL_REF_BASE}/license.rst", + + ( # Allows explaining how to copy anywhere in the doc. + '.. |Example Copy Button| raw:: html\n\n' + '
\n'
+ ' 
\n\n'
+ '
\n\n'
+ )
+
]
-with open("links.rst") as f:
+with open("_includes/links.rst") as f:
PROLOG_PARTS.extend(f.readlines())
rst_prolog = "\n".join(PROLOG_PARTS)
@@ -409,6 +420,29 @@ class A(NamedTuple):
A('doctreedir'),
)
+
+class ResourceRole(SphinxRole): # pending: 3.1
+ """Get resource file and category cross-references sorta working.
+
+ This needs improvement.
+ """
+ def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+ raw = self.text.removeprefix(":resource:")
+ page_id = self.text\
+ .replace(':', '')\
+ .replace('/', '-')\
+ .replace('_', '-')\
+ .replace('.', '-')
+
+ filename = f"'{raw.split('/')[-1]}'"
+ node = nodes.reference(text=filename, refuri=''.join([
+ '/api_docs/resources.html#', page_id]),
+ )
+
+ print("HALP?", locals())
+ return [node], []
+
+
def setup(app):
print("Diagnostic info since readthedocs doesn't use our make.py:")
for attr, comment in APP_CONFIG_DIRS:
@@ -432,7 +466,7 @@ def setup(app):
app.connect('autodoc-process-signature', strip_init_return_typehint, -1000)
app.connect('autodoc-process-bases', on_autodoc_process_bases)
# app.add_transform(Transform)
-
+ app.add_role('resource', ResourceRole())
# ------------------------------------------------------
# Old hacks that breaks the api docs. !!! DO NOT USE !!!
diff --git a/util/create_resources_listing.py b/util/create_resources_listing.py
index 7dd716b75..0aa04010b 100644
--- a/util/create_resources_listing.py
+++ b/util/create_resources_listing.py
@@ -7,16 +7,26 @@
# ruff: noqa
from __future__ import annotations
-import math
+import copy
+import html
import re
import sys
+import textwrap
from collections import defaultdict
+from collections.abc import Mapping
from functools import lru_cache, cache
+from io import StringIO
+from itertools import chain, cycle, islice
from pathlib import Path
-from typing import List, Callable, Protocol
+from typing import List, Callable, Protocol, Sequence, Iterable, TypeVar, NamedTuple
import logging
-log = logging.getLogger(__name__)
+import PIL.Image
+from typing_extensions import TypedDict, NotRequired, Self
+
+FILE = Path(__file__)
+
+log = logging.getLogger(FILE.name)
# Ensure we get utility and Arcade imports first
sys.path.insert(0, str(Path(__file__).parent.resolve()))
@@ -54,7 +64,13 @@ def announce_templating(var_name):
MODULE_DIR = Path(__file__).parent.resolve()
ARCADE_ROOT = MODULE_DIR.parent
RESOURCE_DIR = ARCADE_ROOT / "arcade" / "resources"
-OUT_FILE = ARCADE_ROOT / "doc" / "api_docs" / "resources.rst"
+DOC_ROOT = ARCADE_ROOT / "doc"
+INCLUDES_ROOT = DOC_ROOT / "_includes"
+OUT_FILE = DOC_ROOT / "api_docs" / "resources.rst"
+
+
+class SupportsLT(Protocol):
+ def __lt__(self, other): ...
# Metadata for the resource list: utils\create_resource_list.py
@@ -76,15 +92,6 @@ def skipped_file(file_path: Path):
return file_path.suffix in skip_extensions
-MAX_COLS: dict[str, int] = defaultdict(lambda: 3)
-MAX_COLS[":resources:sounds/"] = 2
-
-
-@lru_cache(maxsize=None)
-def get_header_num_cols(resource_stub: str, n_files = math.inf) -> int:
- return int(min(MAX_COLS[resource_stub], n_files))
-
-
@lru_cache(maxsize=None)
def get_column_widths_for_n(n: int) -> str:
width = str(100 // n)
@@ -92,65 +99,127 @@ def get_column_widths_for_n(n: int) -> str:
@lru_cache(maxsize=None) # Cache b/c re-using elsewhere
-def create_resource_path(
+def path_as_resource_handle(
path: Path,
prefix: str = "",
suffix: str = "",
- restrict_to_bases=('system', 'assets')
+ restrict_to_bases=('system', 'assets'),
+ relative_to: str | Path = RESOURCE_DIR
) -> str:
"""
Create a resource path. We will use the resources handle
and will need to the "assets" and "system" directory
from the path.
"""
- path = path.relative_to(RESOURCE_DIR)
+ path = path.relative_to(relative_to)
base = path.parts[0]
if not restrict_to_bases or base in restrict_to_bases:
path = path.relative_to(base)
else:
- raise ValueError(f"Unexpected path: {path}. Expected one of: {', '.join(repr(b) for b in expect_bases)}")
+ raise ValueError(f"Unexpected path: {path}. Expected one of: {', '.join(repr(b) for b in restrict_to_bases)}")
- return f"{prefix}:resources:{path.as_posix()}{suffix}"
+ parts = [prefix, ":resources:"]
+ as_posix = path.as_posix()
+ if not as_posix.startswith('/'):
+ parts.append('/')
+ parts.extend((as_posix, suffix))
-KENNEY_TTFS = "Kenney TTFs"
-LIBERATION_TTFS = "Liberation TTFs"
+ return ''.join(parts)
+ #return f"{prefix}:resources:{path.as_posix()}{suffix}"
-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,
- "Liberation": LIBERATION_TTFS,
- "gui": "GUI",
- "window": "Window & Panel",
- ".": "Top-level Resources"
+class TableConfigDict(TypedDict):
+ widths: NotRequired[str | Sequence[str | int ]]
+ header_row: NotRequired[Sequence[str]]
+
+
+class HeadingConfigDict(TypedDict):
+ ref_target: NotRequired[str]
+ skip: NotRequired[bool]
+ value: NotRequired[str]
+ level: NotRequired[int]
+
+
+class HandleLevelConfigDict(TypedDict):
+ heading: NotRequired[HeadingConfigDict]
+ include: NotRequired[str]
+ list_table: NotRequired[TableConfigDict]
+
+
+FONT_TABLE_DEFAULTS: TableConfigDict= {
+ 'widths' : (30, 15, 55),
+ 'header_row': (
+ ':py:class:`font_name \n\n'
+ ' via .. raw:: html blocks - # since the CSS may be broken. - out.write("Arcade includes the following fonts from `Kenney.nl's font pack
via .. raw:: html blocks - # since the CSS may be broken. - "\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" - ) - - n_cols = get_header_num_cols(raw_resource_handle, num_files) - widths = get_column_widths_for_n(n_cols) - - # out.write(f"\n{header_title}\n") - # out.write("-" * (len(header_title)) + "\n\n") - - out.write(f"\n") - out.write(f".. raw:: html\n\n") - out.write(f"
{resource_handle}\n")
-
- # pending: post-3.0 cleanup?
- #out.write(f".. list-table:: \"{header_title}\"\n")
- out.write(f".. list-table::\n")
- out.write(f" :widths: {widths}\n")
- out.write(f" :header-rows: 0\n")
- out.write(f" :class: resource-table\n\n")
-
- process_resource_files(out, file_list)
- out.write("\n\n")
-
- process_resource_directory(out, path)
+ return new.getvalue()
-SUFFIX_TO_AUDIO_TYPE = {
- '.wav': 'x-wav',
- '.ogg': 'ogg',
- '.mp3': 'mpeg',
-}
-SUFFIX_TO_VIDEO_TYPE = {
- '.mp4': 'mp4',
- '.webm': 'webm',
- '.avi': 'avi'
+def html_copyable(
+ value: str,
+ resource_handle: str,
+ string_quote_char: str | None = "'"
+) -> str:
+ if string_quote_char:
+ value = f"{string_quote_char}{value}{string_quote_char}"
+ escaped = html.escape(value)
+
+ raw = (
+ f"\n"
+ f" \n"
+ f" {escaped}\n"
+ f" \n"
+ f" \n"
+ f"\n"
+ f"\n\n") + + return raw + + +def highlight_copyable(out, inner: str) -> None: + out.write(f".. code-block:: python\n\n") + out.write(f" {inner!r}\n\n", "") + + +# Regex because why not? We're detecting CapitalWordBounds. +BRITTLE_CAP_WORD_REGEX = re.compile(r"[A-Z][a-z0-9]*") +BRITTLE_FONT_NAME_REGEX = re.compile( + r"""^ + # The 'redundant' \_ escaping improves readability. + (?P
"{resource_copyable}"\n")
- # out.write(f" {path.name} on GitHub\n") - elif suffix in SUFFIX_TO_VIDEO_TYPE: + + out.write(f" {start()} - .. raw:: html\n\n" + + indent(" ", resource_copyable + "\n")) + parts = [] + # out.write(indent(" ", resource_copyable)) + + tile_rst_code = sphinx_directive( + 'image', f'../../{resource_path}', + options={ + 'class':( + 'checkered-bg', # Show transparency via gray tile bg + 'resource-thumb', # Clamp max display size + ), + # lazy helps avoid GitHub and readthedocs from 429ing us ("chill pls") + 'loading': 'lazy', + 'name': resource_handle_no_prefix + } + ) + parts.append(tile_rst_code + "\n") + #out.write(indent(" ", tile_rst_code)) + + size_info = None + if suffix == ".svg": + size_info = "Scalable Vector Graphic" + else: + try: + im = PIL.Image.open(path) + im_width, im_height = im.size + size_info = f"{im_width}px x {im_height}px" + except Exception as e: + log.warning(f"FAILED to read size info for {path}:\n {e}") + + if size_info is None: + size_info = "Could not read size info" + parts.append(f"*({size_info})*\n") + out.write(indent(" ", '\n'.join(parts))) + out.write("\n\n") + + elif suffix in MEDIA_EMBED: + config = MEDIA_EMBED[suffix] + kind = config.get('media_kind') + mime_suffix = config.get('mime_suffix') file_path = FMT_URL_REF_EMBED.format(resource_path) - src_type = SUFFIX_TO_VIDEO_TYPE[suffix] - out.write(f" {start_row} - .. raw:: html\n\n") - out.write(f" \n") - out.write(f"
"{resource_copyable}"\n")
- elif suffix == ".glsl":
- file_path = FMT_URL_REF_PAGE.format(resource_path)
- out.write(f" {start_row} - `{path} <{file_path}>`_\n")
+
+ out.write(f" {start()} - .. raw:: html\n\n")
+ out.write(indent(
+ " ", resource_copyable))
+
+ out.write(f" .. raw:: html\n\n")
+ out.write(indent(" ",
+ f"<{kind} class=\"resource-thumb\" controls>\n"
+ f" {resource_copyable}\n")
- cell_count += 1
+ out.write(f" {start()} - .. raw:: html\n\n")
+ out.write(indent(" ",
+ resource_copyable))
+
+ do_filetile(out, suffix=suffix)
# Finish any remaining columns with empty cells
- while cell_count % COLUMNS > 0:
- out.write(f" -\n")
- cell_count += 1
+ while cell_count % columns > 0:
+ out.write(f" {start()} -\n")
def resources():
@@ -423,7 +741,8 @@ def resources():
do_heading(out, 0, "Built-In Resources")
- out.write("\n")
+ out.write("\n\n:resource:`:resources:/gui_basic_assets/window/panel_green.png`\n\n")
+ # out.write("Linking test: :ref:`resources-gui-basic-assets-window-panel-green-png`.\n")
out.write("Every file below is included when you :ref:`install Arcade \n'
+ # ' \n\n'
+ # '
\n\n'
+ # +
+ "Arcade helps save time through **resource handle** strings. These strings start with\n"
+ "``':resources:'``. After you've installed Arcade, you'll need to:\n\n"
+ "#. Find the copy button (|Example Copy Button|) after a filename below\n"
+ "#. Click it to copy the string, such as ``':resources:/logo.png'``\n"
+ "#. Use the appropriate loading functions to load and display the data\n\n"
+ "Try it below with the Arcade logo, or see the following to learn more\n:"
+ "\n\n"
"* :ref:`Sprite Examples \n\n'
+ # '