RTD remap trick since sphinx hides the config (#2521)

* RTD remap trick since sphinx hides the config

* Comments + we are no longer asking nicely to copy files

Author: pushfoo

doc/conf.py

@@ -2,6 +2,7 @@
 """Sphinx configuration file"""
 from __future__ import annotations
 
+import os
 from functools import cache
 import logging
 from pathlib import Path
@@ -27,8 +28,23 @@
 for i in range(2):
     log.info(f"  {i}: {sys.path[i]!r}")
 
+
+# Grab readthedocs env variables for logging + use
+# https://docs.readthedocs.com/platform/stable/reference/environment-variables.html
+# Their GH comments suggest they want to move away from "magic" injection as
+# part of the readthedocs theme, so this seems like the best option for us.
+log.info(" Env variables...")
+col_width = max(map(len, os.environ.keys()))
+READTHEDOCS = dict()
+ENV = dict()
+for k, v in os.environ.items():
+    if k.startswith('READTHEDOCS_'):
+        READTHEDOCS[k.removeprefix('READTHEDOCS_')] = v
+    ENV[k] = v
+
 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:
@@ -44,6 +60,10 @@
 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}")
 
+print()
+for k, v in ENV.items():
+    log.info(f"Env variable {k:{col_width}} : {v!r}")
+
 # _temp_version = (REPO_LOCAL_ROOT / "arcade" / "VERSION").read_text().replace("-",'')
 
 # Don't change to
@@ -52,26 +72,23 @@
 from version import VERSION # pyright: ignore [reportMissingImports]
 log.info(f" Got version {VERSION!r}")
 
-
 # Check whether the version ends in an all-digit string
-VERSION_PARTS = []
+ARCADE_VERSION_PARTS = []
 for part in VERSION.split('.'):
     if part.isdigit():
-        VERSION_PARTS.append(int(part))
+        ARCADE_VERSION_PARTS.append(part)
     else:
-        VERSION_PARTS.append(part)
+        ARCADE_VERSION_PARTS.append(part)
 
 print()
-if VERSION_PARTS[-1].isdigit():
-    GIT_REF = VERSION
-    log.info(" !!!!! APPEARS TO BE A REAL RELEASE  !!!!!")
+GIT_REF = 'development'
+if READTHEDOCS:
+    if READTHEDOCS.get('VERSION') in ('latest', 'stable'):
+        log.info(" !!!!! APPEARS TO BE A REAL RELEASE  !!!!!")
+    else:
+        log.info(" +++++ Building a PR or development  +++++")
 else:
-    GIT_REF = 'development'
-    log.info(" - - -   Building as a dev release   - - -")
-
-print()
-print(f"   {GIT_REF=!r}")
-print(f"   {VERSION=!r}")
+    log.info(" - - -  Building outside readthedocs  +++++")
 print()
 
 
@@ -80,11 +97,14 @@
 FMT_URL_REF_BASE=f"{REPO_URL_BASE}/blob/{GIT_REF}"
 
 RESOURCE_GLOBALS = dict(
-    GIT_REF=GIT_REF,
+    GIT_REF=GIT_REF,  # pending: post-3.0 clean-up, not sure if things use it now?
+    # This may be more useful according to some doc? (It's unclear)
+    # https://docs.readthedocs.com/platform/stable/reference/environment-variables.html#envvar-READTHEDOCS_GIT_COMMIT_HASH
     BASE_URL_REPO=REPO_URL_BASE,
     # This double-bracket escapes brackets in f-strings
     FMT_URL_REF_PAGE=f"{FMT_URL_REF_BASE}/{{}}",
     FMT_URL_REF_EMBED=f"{FMT_URL_REF_BASE}/{{}}?raw=true",
+    RTD_EVIL=READTHEDOCS['CANONICAL_URL'] if READTHEDOCS else ""  # pending: post-3.0 cleanup
 )
 
 def run_util(filename, run_name="__main__", init_globals=None):
@@ -119,6 +139,8 @@ def run_util(filename, run_name="__main__", init_globals=None):
 run_util('../util/update_quick_index.py')
 
 
+OUT_STATIC = REPO_LOCAL_ROOT / 'build/html/_static/'
+
 src_res_dir = ARCADE_MODULE / 'resources/assets'
 out_res_dir = REPO_LOCAL_ROOT / 'build/html/_static/assets'
 
@@ -133,6 +155,25 @@ def run_util(filename, run_name="__main__", init_globals=None):
 }
 copy_media(src_res_dir, out_res_dir, copy_what)
 
+# We are no longer asking. We are copying.
+copy_media(
+   REPO_LOCAL_ROOT / "doc/_static/icons",
+   OUT_STATIC / "icons" ,
+   {
+       'tabler': ("*.svg",)
+   }
+)
+copy_media(
+   REPO_LOCAL_ROOT / "doc/_static/",
+   OUT_STATIC ,
+   {
+       'filetiles': ("*.png",)
+   }
+)
+#copy_media(
+#    REP / ""
+#)
+
 
 autodoc_inherit_docstrings = False
 autodoc_default_options = {

util/create_resources_listing.py

@@ -43,7 +43,10 @@ def announce_templating(var_name):
 
 # The following are provided via runpy.run_path's init_globals keyword
 # in conf.py. Uncomment for easy debugger run without IDE config.
+_ = RTD_EVIL  # noqa  # explode ASAP or the links will all be broken
+log.info(f" RTD EVIL: {RTD_EVIL!r}")  # noqa
 try:
+
     _ = GIT_REF  # noqa
 except Exception as _:
     GIT_REF = "development"
@@ -61,6 +64,10 @@ def announce_templating(var_name):
     announce_templating("FMT_URL_REF_EMBED")
 
 
+def src_kludge(strpath): # pending: post-3.0 cleanup: # evil evil evil evil
+    """We inject what RTD says the canonical domain is up top + the version"""
+    return f"{RTD_EVIL}{strpath}"
+
 MODULE_DIR = Path(__file__).parent.resolve()
 ARCADE_ROOT = MODULE_DIR.parent
 RESOURCE_DIR = ARCADE_ROOT / "arcade" / "resources"
@@ -495,7 +502,7 @@ def html_copyable(
         f"        <span class=\"pre\">{escaped}</span>\n"
         f"    </code>\n"
         f"    <button class=\"arcade-ezcopy\" data-clipboard-text=\"{resource_handle}\">\n"
-        f"        <img src=\"/{COPY_BUTTON_PATH}\"/>\n"
+        f"        <img src=\"/{src_kludge(COPY_BUTTON_PATH)}\"/>\n"
         # + indent("    " * 2, COPY_BUTTON_RAW) +  # pending: post-3.0 cleanup
         f"    </button>\n"
         f"</span>\n"
@@ -621,17 +628,16 @@ def do_filetile(out, suffix: str | None = None, state: str = None):
         p = FILETILE_DIR / f"type-{suffix.strip('.')}.png"
         log.info(f" FILETILE: {p}")
         if p.exists():
-            print("    KNOWN!")
+            print(f"    KNOWN! {p.name!r}")
             name = p.name
         else:
             name = f"type-unknown.png"
             print("    ... unknown :(")
     else:
         name = "state-error.png"
-
     out.write(indent(f"        ",
                      f".. raw:: html\n\n"
-                     f"   <img class=\"resource-thumb\" src=\"/_static/filetiles/{name}\"/>\n\n"))
+                     f"   <img class=\"resource-thumb\" src=\"{src_kludge('/_static/filetiles/' + name)}\"/>\n\n"))
 
 
 def process_resource_files(
@@ -723,7 +729,7 @@ def start():
             out.write(indent("           ",
                       # Using preload="none" is gentler on GitHub and readthedocs
                       f"<{kind} class=\"resource-thumb\" controls preload=\"none\">\n"
-                      f"  <source src='{file_path}' type='{kind}/{mime_suffix}'>\n"
+                      f"  <source src=\"{src_kludge(file_path)}\" type=\"{kind}/{mime_suffix}\">\n"
                       f"</{kind}>\n\n"))
 
         # Fonts
@@ -743,7 +749,7 @@ def start():
 
         # File tiles we don't have previews for
         else:#  suffix == ".json":
-            file_path = FMT_URL_REF_PAGE.format(resource_path)
+            # file_path = FMT_URL_REF_PAGE.format(resource_path)
             out.write(f"    {start()} - .. raw:: html\n\n")
             out.write(indent("             ",
                  resource_copyable))
@@ -802,7 +808,7 @@ def resources():
         f"   <ol>\n"
         f"      <li>A <strong>file name</strong> as a single-quoted string (<code class=\"docutils literal notranslate\"><span class=\"pre\">{logo}</span></code>)</li>\n"
         f"      <li>A <strong>copy button</strong> to the right of the string (<div class=\"arcade-ezcopy doc-ui-example-dummy\" style=\"display: inline-block;\">"
-        f"<img src=\"/_static/icons/tabler/copy.svg\"></div>)</li>\n"
+        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"

util/doc_helpers/real_filesystem.py

@@ -13,7 +13,7 @@
 
 FILE = Path(__file__)
 REPO_ROOT = Path(__file__).parent.parent.resolve()
-log = logging.getLogger(str(FILE.relative_to(REPO_ROOT)))
+log = logging.getLogger(FILE.name)
 
 
 def dest_older(src: Path | str, dest: Path | str) -> bool:
@@ -89,7 +89,8 @@ def sync_dir(src_dir: Path, dest_dir: Path, *globs: str, done: set | None = None
             log.info(f' Copying media file {src_file} to {dest_file}')
 
             shutil.copyfile(src_file, dest_file)
-
+        else:
+            log.info(f" Skipping media file {src_file} to {dest_file}")
 
 def copy_media(
         src_root: Path | str,