diff --git a/doc/conf.py b/doc/conf.py index 4816a97c30..2b68f260b6 100644 --- a/doc/conf.py +++ b/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 = { diff --git a/util/create_resources_listing.py b/util/create_resources_listing.py index 1f453ed5f6..8581ff94e1 100644 --- a/util/create_resources_listing.py +++ b/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" {escaped}\n" f" \n" f" \n" f"\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" \n\n")) + f" \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" \n" + f" \n" f"\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"
    \n" f"
  1. A file name as a single-quoted string ({logo})
    2. \n" f"
  2. A copy button to the right of the string (
    " - f"
    )
    3. \n" + f")\n" f"
\n\n" + "Click the button above a preview to copy the **resource handle** string for loading the asset.\n" diff --git a/util/doc_helpers/real_filesystem.py b/util/doc_helpers/real_filesystem.py index 911c8083a9..aa3478776b 100644 --- a/util/doc_helpers/real_filesystem.py +++ b/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,