Add initial improved click-to-copy for resources page (#2514)

* WIP: face name and table generation

* HIDEOUS code

* WIP-ish with tiled images

* Copyables copy but too wide and ugly.

* Move resources info sections into includes files

* Create doc/_includes

* Move links.rst there

* Move the resource inclusion there using the include_file feature from the Vfs

* Move ref check to function for it

* WIP we have non-huge copy buttons

* Add custom JS to the force-copy temp fix and clean up header

* Add custom JS call to target ezcopy class

* Add CSS for buttons

* Very ugly code for generating the buttons

* WIP commit: seems to render correctly

* Clean up table body generation

* Move image tile to new function

* Add unknown file handling and clean up more

* More indents

* Add first draft of inlinable literals for Arcade

* Wrap the literal and button in a span

* Add styling

* Remove indent argument from function likely to be removed soon

* Move and comment some things

* Quote fix + explain  how / why it works

* Remove kludges and improve column durability

* Use iterators instead of non-stop modulo and variable references

* Simplify column detection: 1 column when n=1, 3 for fonts, 2 for all else

* Add arguments to allow passing in the value to the table generation from outside

* Improve clarity and durability for resource paths

* fix missing variable name in create_resources_path

* rename create_resources_path to path_as_resource_handle:

* Fix wrong quoting behavior for copyable embeds

* s/quote(/html_quote(/g

* use better resource paths

* explain a few things better

* Partly switch over to a clean nested config dict

* Start switching over config reading

* Partly decruft the methods

* Remove cruft config storage replaced in last commit

* Re-enable resource handle prefix as table caption

* Use Python's standard library to handle HTML escaping

* Remove custom html quote function

* Add prefix of handle string as table caption with CSS to make it match the copyables more

* Clean imports, constants, and commented-out code

* Whitespace + more redundancies removed

* Encapsulate font data parsing from filenames

* Unify media embeds

* Fix header row generation + move a few things

* Fix include behavior + add copy button directions

* Fix heading generation and start improving the ordering for auto-generation

* Fix the include ordering for the resources pages

* Add site-wide |Copy Button substitution

* Add rough instructions for the copy buttons based on feedback

* Encapsulate table header + header row behavior

* Some more consolidation

* Separate concerns for table body, header, and conf

* Add basic file tile thumbing (ty @DigiDuncan)

* Remove old thumbnailing for unknown files

* Remove code from .rst generation

* Remove CSS supporting the .. raw:: html for unknown file types

* Improve example copy button (almost-correct style)

* Styles almost correctly with hover (inline is breaking)

* Add .doc-ui-example-dummy class intended to shut off UI behavior on dummy elements

* CSS changes to support the UI elements and on-page instructions

* Document some flaws better

* Add |Example Copy Button| substitution for Sphinx embeds

* Add fall state as a stop-gap for the blue alien

* Remove more cruft

* Remove unused code + extra whitespace in a regex

* Remove linking experiment for now

* Switch glsl shader listing off again

* Doc cross-ref trick works sorta?

doc/_includes/resources_Image_Theme_Sets.rst

@@ -0,0 +1,3 @@
+Arcade includes an number of themed image sets to help you get started
+making specific types of games. Some of these help you complete the tutorials
+while others are general-purpose prototyping tools.

doc/_includes/resources_Kenney.rst

@@ -0,0 +1,9 @@
+.. figure:: images/fonts_blue.png
+   :align: center
+   :alt: The bundled Kenney.nl fonts.
+
+.. Put the text *after* the CSS, or add <br> via .. raw:: html blocks
+.. since the CSS may be broken.
+
+Arcade includes the following fonts from `Kenney.nl's font pack <https://kenney.nl/assets/kenney-fonts>`_
+are available using the path and filenames below.

doc/_includes/resources_Liberation.rst

@@ -0,0 +1,15 @@
+.. figure:: images/fonts_liberation.png
+   :alt: The bundled Liberation font family trio.
+   :align: center
+
+.. Put the text *after* the CSS, or add <br> 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`.

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!
+

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;

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');
 });

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'
+        '   <div class="arcade-ezcopy doc-ui-example-dummy" style="display: inline-block;">\n'
+        '      <img src="/_static/copy-button.svg"/>\n\n'
+        '   </div>\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 !!!