Fix CSS breakage for instructions and embeds ahead of 3.0 (#2520)

* Temp-fix brittle dev release name handling

* Syncs sound, music, and video now

* Comment out ref generation for embeds

* Clean up embed code

* Add anti-preload hints

* Temp fix copy buttons of both kinds

* Clean up some support code

* Clean up conf.py + move things to a utils item

* Comments

* Fix resource handle copyables for smaller display ports

* Get resource page cleaned up with usage instructions

* Fix CSS

* Fix generation and add explanation of videos

* Some proofreading and experimental warnings

* Remove big commented-out block

Author: pushfoo

doc/_includes/resources_Top-Level_Resources.rst

@@ -1,8 +1,25 @@
 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
+.. raw:: html
 
-Paste in your favorite text editor!
+   <ol>
+      <li>Look down toward the Arcade logo below until you see the file name<li>
+      <li>Look to the right edge of the file name (<code class="docutils literal notranslate"><span class="pre">'logo.png'</span></code>)</li>
+      <li>There should be a copy button <(<div class="arcade-ezcopy doc-ui-example-dummy" style="display: inline-block;">
+        <img src="/_static/icons/tabler/copy.svg"></div>) </li>
+      <li>Click or tap it.</li>
+   </ol>
 
+Click the button or tap it if you're on mobile. Then try pasting in your favorite text editor. It
+should look like this::
+
+  ':resources:/logo.png'
+
+This string is what Arcade calls a **:ref:`resource handle <resource_handles>`**. They let you load
+images, sound, and other data without worrying about where exactly data is on a computer. To learn
+more, including how to define your own handle prefix, see :ref:`resource_handles`.
+
+To get started with game code right away, please see the following:
+
+* :ref:`example-code`
+* :ref:`main-page-tutorials`

doc/_includes/resources_Video.rst

@@ -0,0 +1,24 @@
+.. _resources_video:
+
+Video
+-----
+
+Arcade offers experimental support for video playback through :py:mod:`pyglet` and other libraries.
+
+.. warning:: These features are works-in-progress!
+
+   Please the following to learn more:
+
+   * :ref:`future_api`
+   * The undocumented `experimental folder <https://github.com/pythonarcade/arcade/tree/development/arcade/experimental>`_
+
+To make testing easier, Arcade includes the small video file embedded below. However, runnign the
+examples below may require installing both :ref:`guide-supportedmedia-ffmpeg` and additional libraries:
+
+* The `cv2-based video examples <https://github.com/pythonarcade/arcade/blob/development/arcade/future/video/>`_
+* The `cv2-based shadertoy example <https://github.com/pythonarcade/arcade/blob/development/arcade/experimental/shadertoy_video_cv2.py>`_
+
+The links above use the unstable development branch of Arcade to gain access to the latest :py:mod:`pyglet`
+and Arcade features. If you have questions or want to help develop these examples further, we'd love to hear
+from you. The Arcade `Discord server <Arcade Discord>`_ and `GitHub repository <Arcade GitHub>`_ always welcome
+new community members.

doc/_static/css/custom.css

@@ -262,11 +262,18 @@ table.resource-table td > .resource-thumb.file-icon {
 
 
 .resource-handle {
-    display: inline-block;
+    /* Flex props keep this all on one line when the viewport with's small */
+    display: inline-flex;
+    flex-direction: row;
+    flex-shrink: 0;
+
+    /* Make the button round so it's nice-looking */
     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;
@@ -314,20 +321,28 @@ table.resource-table td > .resource-thumb.file-icon {
 .resource-table * > .literal:has(+ button.arcade-ezcopy) {
      border-radius: 0.4em 0 0 0.4em !important;
 }
-.resource-table  .literal + button.arcade-ezcopy {
+.resource-table * > .literal + button.arcade-ezcopy {
      border-radius: 0 0.4em 0.4em 0 !important;
 }
 
 
-
-.arcade-ezcopy > img {
+.arcade-ezcopy > *:is(img, svg) {
     margin: 0;
     width: 100%;
+    max-width: 100%;
     height: 100%;
+    max-height: 100%;
 }
 .arcade-ezcopy:hover {
   background-color: #54c079;
 }
+/* Give it some breathing room inside the inline HTML we're using for the moment
+  # pending: post-3.0 clean-up
+*/
+li .arcade-ezcopy.doc-ui-example-dummy {
+    margin-left: 0.2em;
+    margin-right: 0.2em;
+}
 
 table.colorTable {
     border-width: 1px;

doc/_static/icons/tabler/copy.svg

@@ -1,23 +1,34 @@
 #!/usr/bin/env python
 """Sphinx configuration file"""
 from __future__ import annotations
+
 from functools import cache
 import logging
 from pathlib import Path
-from textwrap import dedent
 from typing import Any, NamedTuple
-import docutils.nodes
-import os
 import re
 import runpy
-import sphinx.ext.autodoc
-import sphinx.transforms
 import sys
 
 from docutils import nodes
-from docutils.nodes import literal
 from sphinx.util.docutils import SphinxRole
 
+HERE = Path(__file__).resolve()
+REPO_LOCAL_ROOT = HERE.parent.parent
+ARCADE_MODULE = REPO_LOCAL_ROOT / "arcade"
+UTIL_DIR = REPO_LOCAL_ROOT / "util"
+
+log = logging.getLogger('conf.py')
+logging.basicConfig(level=logging.INFO)
+
+sys.path.insert(0, str(REPO_LOCAL_ROOT))
+sys.path.insert(0, str(ARCADE_MODULE))
+log.info(f"Inserted elements in system path: First two are now:")
+for i in range(2):
+    log.info(f"  {i}: {sys.path[i]!r}")
+
+from util.doc_helpers.real_filesystem import copy_media
+
 # 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:
@@ -27,44 +38,47 @@
 
 # --- Pre-processing Tasks
 
-log = logging.getLogger('conf.py')
-logging.basicConfig(level=logging.INFO)
-
-HERE = Path(__file__).resolve()
-REPO_LOCAL_ROOT = HERE.parent.parent
-
-ARCADE_MODULE = REPO_LOCAL_ROOT / "arcade"
-UTIL_DIR = REPO_LOCAL_ROOT / "util"
-
+# Report our diagnostic info
 log.info(f"Absolute path for our conf.py       : {str(HERE)!r}")
 log.info(f"Absolute path for the repo root     : {str(REPO_LOCAL_ROOT)!r}")
 log.info(f"Absolute path for the arcade module : {str(REPO_LOCAL_ROOT)!r}")
 log.info(f"Absolute path for the util dir      : {str(UTIL_DIR)!r}")
 
 # _temp_version = (REPO_LOCAL_ROOT / "arcade" / "VERSION").read_text().replace("-",'')
 
-sys.path.insert(0, str(REPO_LOCAL_ROOT))
-sys.path.insert(0, str(ARCADE_MODULE))
-log.info(f"Inserted elements in system path: First two are now:")
-for i in range(2):
-    log.info(f"  {i}: {sys.path[i]!r}")
-
 # Don't change to
 # from arcade.version import VERSION
 # or read the docs build will fail.
 from version import VERSION # pyright: ignore [reportMissingImports]
-log.info(f"Got version {VERSION!r}")
+log.info(f" Got version {VERSION!r}")
 
-REPO_URL_BASE="https://github.com/pythonarcade/arcade"
-if 'dev' in VERSION:
-    GIT_REF = 'development'
-    log.info(f"Got .dev release: using {GIT_REF!r}")
-else:
+
+# Check whether the version ends in an all-digit string
+VERSION_PARTS = []
+for part in VERSION.split('.'):
+    if part.isdigit():
+        VERSION_PARTS.append(int(part))
+    else:
+        VERSION_PARTS.append(part)
+
+print()
+if VERSION_PARTS[-1].isdigit():
     GIT_REF = VERSION
-    log.info(f"Got real release: using {GIT_REF!r}")
+    log.info(" !!!!! APPEARS TO BE A REAL RELEASE  !!!!!")
+else:
+    GIT_REF = 'development'
+    log.info(" - - -   Building as a dev release   - - -")
+
+print()
+print(f"   {GIT_REF=!r}")
+print(f"   {VERSION=!r}")
+print()
+
 
 # We'll pass this to our generation scripts to initialize their globals
+REPO_URL_BASE="https://github.com/pythonarcade/arcade"
 FMT_URL_REF_BASE=f"{REPO_URL_BASE}/blob/{GIT_REF}"
+
 RESOURCE_GLOBALS = dict(
     GIT_REF=GIT_REF,
     BASE_URL_REPO=REPO_URL_BASE,
@@ -104,6 +118,22 @@ def run_util(filename, run_name="__main__", init_globals=None):
 # Run the generate quick API index script
 run_util('../util/update_quick_index.py')
 
+
+src_res_dir = ARCADE_MODULE / 'resources/assets'
+out_res_dir = REPO_LOCAL_ROOT / 'build/html/_static/assets'
+
+# pending: post-3.0 cleanup to find the right source events to make this work?
+# if exc or app.builder.format != "html":
+#     return
+# static_dir = (app.outdir / '_static').resolve()
+copy_what = {  # pending: post-3.0 cleanup to tie this into resource generation correctly
+    'sounds': ('*.wav', '*.ogg', '*.mp3'),
+    'music': ('*.wav', '*.ogg', '*.mp3'),
+    'video': ('*.mp4', '*.webm', )
+}
+copy_media(src_res_dir, out_res_dir, copy_what)
+
+
 autodoc_inherit_docstrings = False
 autodoc_default_options = {
     'members': True,
@@ -136,6 +166,12 @@ def run_util(filename, run_name="__main__", init_globals=None):
     'doc.extensions.prettyspecialmethods',  # Forker plugin for prettifying special methods
 ]
 
+# pending: post-3.0 cleanup:
+# 1. Setting this breaks the CSS for both the plugin's buttons and our "custom" ones
+# 2. Since our custom ones are only on the gui page for now, it's okay
+# Note: tabler doesn't require attribution + it's the original theme for this icon set
+# copybutton_image_svg = (REPO_LOCAL_ROOT / "doc/_static/icons/tabler/copy.svg").read_text()
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -272,7 +308,6 @@ def run_util(filename, run_name="__main__", init_globals=None):
 rst_prolog = "\n".join(PROLOG_PARTS)
 
 
-
 def strip_init_return_typehint(app, what, name, obj, options, signature, return_annotation):
     # Prevent a the `-> None` annotation from appearing after classes.
     # This annotation comes from the `__init__`, but it renders on the class,
@@ -281,6 +316,7 @@ def strip_init_return_typehint(app, what, name, obj, options, signature, return_
     if what == "class" and return_annotation is None:
         return (signature, None)
 
+
 def inspect_docstring_for_member(
     _app,
     what: str,
@@ -407,7 +443,6 @@ def on_autodoc_process_bases(app, name, obj, options, bases):
     bases[:] = [base for base in bases if base is not object]
 
 
-
 class A(NamedTuple):
     dirname: str
     comment: str = ""
@@ -439,7 +474,7 @@ def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]:
              '/api_docs/resources.html#', page_id]),
             )
 
-        print("HALP?", locals())
+        log.info(" Attempted ResourceRole", locals())
         return [node], []
 
 
@@ -452,6 +487,7 @@ def setup(app):
             print(f"    {comment}")
 
     # Separate stylesheets loosely by category.
+    # pending:  sphinx >= 8.1.4 to remove the sphinx_static_file_temp_fix.py
     app.add_css_file("css/colors.css")
     app.add_css_file("css/layout.css")
     app.add_css_file("css/custom.css")
@@ -467,6 +503,8 @@ def setup(app):
     app.connect('autodoc-process-bases', on_autodoc_process_bases)
     # app.add_transform(Transform)
     app.add_role('resource', ResourceRole())
+    # Don't do anything that can fail on this event or it'll kill your build hard
+    # app.connect('build-finished', throws_exception)
 
 # ------------------------------------------------------
 # Old hacks that breaks the api docs. !!! DO NOT USE !!!