Fix GitHub stars on the home page, our pyglet intersphinx config, and small issues on resources

doc/_includes/resources_Top-Level_Resources.rst

@@ -1,4 +1,4 @@
-This logo of the snake doubles as a quick way to test Arcade's resource handles.
+The Arcade logo doubles as a quick way to test :ref:`resource handles <resource_handles>`.
 
 .. raw:: html
 
@@ -7,19 +7,6 @@ This logo of the snake doubles as a quick way to test Arcade's resource handles.
       <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="https://api.arcade.academy/en/development/_static/icons/tabler/copy.svg"></div>) </li>
-      <li>Click or tap it.</li>
+      <li>Click or tap it to copy the string</li>
+      <li>Try pasting it in your favorite text editor!</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

@@ -1,8 +1,3 @@
-.. _resources_video:
-
-Video
------
-
 Arcade offers experimental support for video playback through :py:mod:`pyglet` and other libraries.
 
 .. warning:: These features are works-in-progress!

doc/_static/css/custom.css

@@ -57,12 +57,15 @@ title + list appear like other categories */
     width: 100%;
 }
 
-/* Wrappers and formatting for sprinter, START HERE, github star button
-to align them neatly */
+/* Align the GitHub stars button since Sphinx doesn't offer us great control over headings */
 .main-page-item-wrapper-header {
     align-items: center;
-    display: flex;
-    margin: 10px;
+    float: right;
+    display: relative;
+}
+/* IMPORTANT: unlike flex, you have to clear float! */
+.main-page-item-wrapper-header::after {
+    float: clear;
 }
 .main-page-box {
     width: 100%;
@@ -97,7 +100,8 @@ to align them neatly */
     width: 100%;
     display: flex;
 } */
-.main-page-box > .main-page-box-gh {
+
+.main-page-box-gh {
     display: flex;
     align-items: center;
     margin-right: 0px;
@@ -342,6 +346,9 @@ table.resource-table td > .resource-thumb.file-icon {
 li .arcade-ezcopy.doc-ui-example-dummy {
     margin-left: 0.2em;
     margin-right: 0.2em;
+    /* Override 12 px bottom margin */
+    margin-top: inherit !important;
+    margin-bottom: inherit !important;
 }
 
 table.colorTable {

doc/conf.py

@@ -323,7 +323,9 @@ def run_util(filename, run_name="__main__", init_globals=None):
 # Configuration for intersphinx enabling linking other projects
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
-    'pyglet': ('https://pyglet.readthedocs.io/en/development/', None),
+    # As of January 25th, pyglet's 2.1.X branch is on this URL and their
+    # development build on readthedocs is for their in-progress 3.0.0 alpha.
+    'pyglet': ('https://pyglet.readthedocs.io/en/latest/', None),
     'PIL': ('https://pillow.readthedocs.io/en/stable', None),
     'pymunk': ('https://www.pymunk.org/en/latest/', None),
 }

doc/index.rst

@@ -1,32 +1,26 @@
 :hide-toc:
 
+.. container:: main-page-item-wrapper-header
+
+    .. raw:: html
+
+       <div class="main-page-box-gh">
+          <iframe id="github-stars" style="align-self: center; margin: 0 auto; display: block;"
+            src="https://ghbtns.com/github-btn.html?user=pythonarcade&repo=arcade&type=star&count=true&size=large"
+            frameborder="0"
+            scrolling="0"
+            title="GitHub">
+          </iframe>
+       </div>
 
 .. _main_page:
 
 The Python Arcade Library
 =========================
 
-
-.. container:: main-page-item-wrapper-header
-
-    .. raw:: html
-
-        <div class="main-page-box">
-            <div class="main-page-link">
-            </div>
-            <div class="main-page-box-gh">
-               <iframe id="github-stars" style="align-self: center; margin: 0 auto; display: block;"
-                        src="https://ghbtns.com/github-btn.html?user=pythonarcade&repo=arcade&type=star&count=true&size=large"
-                        frameborder="0"
-                        scrolling="0"
-                        title="GitHub">
-               </iframe>
-            </div>
-        </div>
-
 Arcade is an easy-to-learn Python library for creating 2D games and more. The
-friendly API caters to both beginners and experts alike. Do you want to make
-something small, or explore the full power of shaders? It's up to you.
+friendly API caters to both beginners and experts alike. Do you want to craft
+craft your take on a 2D classic, or explore the full power of shaders? It's up to you.
 
 What will you make?
 

util/create_resources_listing.py

@@ -143,7 +143,7 @@ class TableConfigDict(TypedDict):
 
 
 class HeadingConfigDict(TypedDict):
-    ref_target: NotRequired[str | bool]
+    ref_target: NotRequired[str]
     skip: NotRequired[bool]
     value: NotRequired[str]
     level: NotRequired[int]
@@ -169,6 +169,7 @@ class HandleLevelConfigDict(TypedDict):
     ":resources:/": {
         "heading": {
             "value": "Top-Level Resources",
+            "ref_target": "resources-top-level-resources",
             "level": 1
         },
         "include": "resources_Top-Level_Resources.rst"
@@ -208,10 +209,10 @@ class HandleLevelConfigDict(TypedDict):
     },
     ":resources:/video/": {
         # pending: post-3.0 cleanup # trains are hats
-        # "heading:": {
-        #     "value": "Video",
-        #     "ref_target": "resources_video"
-        # },
+        "heading:": {
+            "value": "Video",
+            "ref_target": "resources_video"
+        },
         "include": "resources_Video.rst"
     }
 }
@@ -273,6 +274,7 @@ def do_heading(
     if ref_target is True:
         ref_target = f"resources-{heading_text}.rst"
     if ref_target:
+        print(f"   writing ref target {repr(heading_text)}")
         out.write(f".. _{ref_target.lower()}:\n\n")
 
     if relative_heading_level >= num_headings:
@@ -427,19 +429,24 @@ def process_resource_directory(out, dir: Path):
                 local_config = RESOURCE_HANDLE_CONFIGS.get(handle_step_whole, {})
                 local_heading_config = local_config.get('heading', {})
 
-                # print("proceeding...",
-                #       "\n   config         ", local_config,
-                #       "\n   heading_config ", local_heading_config, sep = "")
+                print("proceeding...",
+                      "\n   config         ", local_config,
+                      "\n   heading_config ", local_heading_config, sep = "")
 
                 # Heading config fetch and write
                 use_level = local_heading_config.get('level', heading_level)
                 use_value = local_heading_config.get('value', None)
+                use_target = local_heading_config.get('ref_target', None)
                 if use_value is None:
                     use_value = format_title_part(handle_steps_parts[heading_level])
-                use_target = local_heading_config.get('ref_target', None)
-                if isinstance(use_target, bool) and use_target:
-                    use_target = f"resources_{use_value.lower()}"
+                if use_target is None:
+                    use_target = f"resources-{use_value.lower()}"
+
+                for k, v in locals().items():
+                    if k.startswith("use_"):
+                        print(repr(k), ":", repr(v))
 
+                print(f"  got target: {use_target!r}")
                 do_heading(out, use_level, use_value, ref_target=use_target)
                 out.write(f"\n.. comment `{handle_step_whole!r}``\n\n")
 
@@ -788,7 +795,7 @@ def resources():
               "convenience, or visit `Kenney.nl`_ for more permissively licensed game assets.\n"
               "\n" 
               "The one feature which may require additional software is Arcade's experimental video playback\n"
-              "support. The :ref:`resources_video` section below will explain further.\n")
+              "support. The :ref:`resources-video` section below will explain further.\n")
 
     do_heading(out, 1, "Do I have to credit anyone?")
     # Injecting the links.rst doesn't seem to be working?
@@ -814,9 +821,18 @@ def resources():
         f"<img src=\"{src_kludge('/_static/icons/tabler/copy.svg')}\"></div>)</li>\n"
         f"   </ol>\n\n"
         +
-        "Click the button above a preview to copy the **resource handle** string for loading the asset.\n"
-        "Any image or sound on this page should work after installing Arcade with zero additional dependencies.\n"
-        "Full example code and manual sections for any relevant functions are linked below."
+        "Click the button above a preview to copy the **resource handle** string for loading the asset. It should\n"
+        "look something like this::\n\n"
+        "  ':resources:/logo.png'\n"
+        "\n"
+        "Each resource preview on this page has a button which copies a corresponding string. These\n"
+        "resource handle strings allow using Arcade's built-in assets without worrying where a file is\n"
+        "on a computer.\n\n"
+        "To learn more, please see:\n\n"
+        "* The :ref:`resources-top-level-resources` section for a short tutorial on resource handles\n"
+        "* :ref:`example-code` for runnable example code\n"
+        "* :ref:`main-page-tutorials` for a step-by-step introduction to Arcade\n"
+        "* :ref:`resource_handles` for in-depth explanations of resource handles\n\n"
     )
 
     out.write("\n")