From baa222498dcfea188167f11788b620371dd432ca Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sun, 19 Jan 2025 14:39:34 -0500 Subject: [PATCH 1/8] Add temp fix for Sphinx failing to copy static files --- doc/conf.py | 50 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 36ded57027..4d6c6e719a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,6 +1,8 @@ #!/usr/bin/env python """Sphinx configuration file""" from __future__ import annotations + +import shutil from functools import cache import logging from pathlib import Path @@ -27,15 +29,60 @@ logging.basicConfig(level=logging.INFO) HERE = Path(__file__).resolve() -REPO_LOCAL_ROOT = HERE.parent.parent +DOC_DIR = HERE.parent +REPO_LOCAL_ROOT = DOC_DIR.parent + +STATIC_SOURCE_DIR = DOC_DIR / "_static" ARCADE_MODULE = REPO_LOCAL_ROOT / "arcade" UTIL_DIR = REPO_LOCAL_ROOT / "util" +BUILD_DIR = REPO_LOCAL_ROOT / "build" +BUILD_HTML_DIR = BUILD_DIR / "html" +BUILD_STATIC_DIR = BUILD_HTML_DIR / "_static" + 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}") +STATIC_CSS_DIR = STATIC_SOURCE_DIR / "css" +# Make it move because Sphinx only fixed the copy issue as of a few days ago +# https://github.com/sphinx-doc/sphinx/pull/13236 +# https://github.com/sphinx-doc/sphinx/issues/1810 +force_copy_on_change = { # pending: sphinx >= 8.1.4 + source_file: BUILD_STATIC_DIR / f"css/{source_file.name}" + for source_file in STATIC_CSS_DIR.glob("*.css") +} + + +def force_sync(src, dest, dry: bool = False): + if sphinx.__version__ >= '8.1.4': + log.warning( + 'Sphinx >= 8.1.4 may patch broken _static copy\n' + ' (see https://github.com/sphinx-doc/sphinx/issues/1810)') + try: + if src.read_text() != dest.read_text(): + if dry: + log.info(f" DRY : {src} was out of date, but dry run left it as-is!") + # shutil.copyfile(src, dest) + else: + log.info(f" SYNC: {src} was out of date!") + + else: + log.info(f" SKIP: {src} is current!") + except Exception as e: + log.error(f" FAIL: {src} failed: {e}") + raise e + + +if BUILD_HTML_DIR.exists(): + for src, dest in force_copy_on_change.items(): + force_sync(src, dest) +else: + log.info("Skipping force-sync due to no build dir") + + + # _temp_version = (REPO_LOCAL_ROOT / "arcade" / "VERSION").read_text().replace("-",'') sys.path.insert(0, str(REPO_LOCAL_ROOT)) @@ -44,6 +91,7 @@ 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 241b9e781e465944b7ee6dceb08ac9b8715c8c79 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sun, 19 Jan 2025 14:52:10 -0500 Subject: [PATCH 2/8] Gate the temp fix feature behind a dev-machine specific file --- .gitignore | 4 ++++ doc/conf.py | 18 +++++++++++------- 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/.gitignore b/.gitignore index afafff92b8..d079dc7e0f 100644 --- a/.gitignore +++ b/.gitignore @@ -58,3 +58,7 @@ temp/ .python-version .flake8 + +# pending: Sphinx 8.1.4 + deps are verified as workin with arcade +# this works around an annoying static copy issue +.ENABLE_DEVMACHINE_SPHINX_STATIC_FIX \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index 4d6c6e719a..ad008a9af5 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -32,29 +32,31 @@ DOC_DIR = HERE.parent REPO_LOCAL_ROOT = DOC_DIR.parent +# pending: Sphinx 8.1.4 + deps verified as compatible with Arcade to fix static copy +# Make it move because Sphinx only fixed the copy issue as of a few days ago +# https://github.com/sphinx-doc/sphinx/pull/13236 +# https://github.com/sphinx-doc/sphinx/issues/181 +ENABLE_DEVMACHINE_SPHINX_STATIC_FIX = REPO_LOCAL_ROOT / ".ENABLE_DEVMACHINE_SPHINX_STATIC_FIX" STATIC_SOURCE_DIR = DOC_DIR / "_static" + ARCADE_MODULE = REPO_LOCAL_ROOT / "arcade" UTIL_DIR = REPO_LOCAL_ROOT / "util" BUILD_DIR = REPO_LOCAL_ROOT / "build" BUILD_HTML_DIR = BUILD_DIR / "html" BUILD_STATIC_DIR = BUILD_HTML_DIR / "_static" - 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}") + STATIC_CSS_DIR = STATIC_SOURCE_DIR / "css" -# Make it move because Sphinx only fixed the copy issue as of a few days ago -# https://github.com/sphinx-doc/sphinx/pull/13236 -# https://github.com/sphinx-doc/sphinx/issues/1810 force_copy_on_change = { # pending: sphinx >= 8.1.4 source_file: BUILD_STATIC_DIR / f"css/{source_file.name}" for source_file in STATIC_CSS_DIR.glob("*.css") } - def force_sync(src, dest, dry: bool = False): if sphinx.__version__ >= '8.1.4': log.warning( @@ -75,14 +77,16 @@ def force_sync(src, dest, dry: bool = False): raise e -if BUILD_HTML_DIR.exists(): +if not ENABLE_DEVMACHINE_SPHINX_STATIC_FIX.exists(): + log.info(f"SKIP: Force-sync found no {ENABLE_DEVMACHINE_SPHINX_STATIC_FIX} file!") +elif BUILD_HTML_DIR.exists(): + log.info(f"SYNC: Force-sync enable file found") for src, dest in force_copy_on_change.items(): force_sync(src, dest) else: log.info("Skipping force-sync due to no build dir") - # _temp_version = (REPO_LOCAL_ROOT / "arcade" / "VERSION").read_text().replace("-",'') sys.path.insert(0, str(REPO_LOCAL_ROOT)) From 8c3320a5e289e4c79873afdeae266dc85419a237 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sun, 19 Jan 2025 16:07:42 -0500 Subject: [PATCH 3/8] Move the temp fix into a contained script file + update .gitignore comment --- .gitignore | 4 +- doc/conf.py | 48 +--------------- util/sphinx_static_file_temp_fix.py | 89 +++++++++++++++++++++++++++++ 3 files changed, 94 insertions(+), 47 deletions(-) create mode 100644 util/sphinx_static_file_temp_fix.py diff --git a/.gitignore b/.gitignore index d079dc7e0f..8d2b38dd22 100644 --- a/.gitignore +++ b/.gitignore @@ -59,6 +59,6 @@ temp/ .flake8 -# pending: Sphinx 8.1.4 + deps are verified as workin with arcade -# this works around an annoying static copy issue +# pending: Sphinx 8.1.4 + deps are verified as working with Arcade +# see util/sphinx_static_file_temp_fix.py .ENABLE_DEVMACHINE_SPHINX_STATIC_FIX \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index ad008a9af5..3177698e2b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -32,18 +32,11 @@ DOC_DIR = HERE.parent REPO_LOCAL_ROOT = DOC_DIR.parent -# pending: Sphinx 8.1.4 + deps verified as compatible with Arcade to fix static copy -# Make it move because Sphinx only fixed the copy issue as of a few days ago -# https://github.com/sphinx-doc/sphinx/pull/13236 -# https://github.com/sphinx-doc/sphinx/issues/181 -ENABLE_DEVMACHINE_SPHINX_STATIC_FIX = REPO_LOCAL_ROOT / ".ENABLE_DEVMACHINE_SPHINX_STATIC_FIX" -STATIC_SOURCE_DIR = DOC_DIR / "_static" - ARCADE_MODULE = REPO_LOCAL_ROOT / "arcade" UTIL_DIR = REPO_LOCAL_ROOT / "util" BUILD_DIR = REPO_LOCAL_ROOT / "build" BUILD_HTML_DIR = BUILD_DIR / "html" -BUILD_STATIC_DIR = BUILD_HTML_DIR / "_static" + 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}") @@ -51,42 +44,6 @@ log.info(f"Absolute path for the util dir : {str(UTIL_DIR)!r}") -STATIC_CSS_DIR = STATIC_SOURCE_DIR / "css" -force_copy_on_change = { # pending: sphinx >= 8.1.4 - source_file: BUILD_STATIC_DIR / f"css/{source_file.name}" - for source_file in STATIC_CSS_DIR.glob("*.css") -} - -def force_sync(src, dest, dry: bool = False): - if sphinx.__version__ >= '8.1.4': - log.warning( - 'Sphinx >= 8.1.4 may patch broken _static copy\n' - ' (see https://github.com/sphinx-doc/sphinx/issues/1810)') - try: - if src.read_text() != dest.read_text(): - if dry: - log.info(f" DRY : {src} was out of date, but dry run left it as-is!") - # shutil.copyfile(src, dest) - else: - log.info(f" SYNC: {src} was out of date!") - - else: - log.info(f" SKIP: {src} is current!") - except Exception as e: - log.error(f" FAIL: {src} failed: {e}") - raise e - - -if not ENABLE_DEVMACHINE_SPHINX_STATIC_FIX.exists(): - log.info(f"SKIP: Force-sync found no {ENABLE_DEVMACHINE_SPHINX_STATIC_FIX} file!") -elif BUILD_HTML_DIR.exists(): - log.info(f"SYNC: Force-sync enable file found") - for src, dest in force_copy_on_change.items(): - force_sync(src, dest) -else: - log.info("Skipping force-sync due to no build dir") - - # _temp_version = (REPO_LOCAL_ROOT / "arcade" / "VERSION").read_text().replace("-",'') sys.path.insert(0, str(REPO_LOCAL_ROOT)) @@ -140,6 +97,8 @@ def run_util(filename, run_name="__main__", init_globals=None): runpy.run_path(full_str, **kwargs) +run_util("sphinx_static_file_temp_fix.py") + # Make thumbnails for the example code screenshots run_util("generate_example_thumbnails.py") # Create a tabular representation of the resources with embeds @@ -147,7 +106,6 @@ def run_util(filename, run_name="__main__", init_globals=None): # Run the generate quick API index script run_util('../util/update_quick_index.py') - autodoc_inherit_docstrings = False autodoc_default_options = { 'members': True, diff --git a/util/sphinx_static_file_temp_fix.py b/util/sphinx_static_file_temp_fix.py new file mode 100644 index 0000000000..4f0434b44b --- /dev/null +++ b/util/sphinx_static_file_temp_fix.py @@ -0,0 +1,89 @@ +#!/usr/bin/env python3 +""" +A quick, ugly fix for a broken static file handler. + +This runs sync over static folders entries crucial for web dev +which Sphinx <= 8.1.3 does not properly handle due to early exit +checks. Keep the following in mind: + +1. It is not tested to work with sphinx-autobuild or ./make.py serve +2. It was created for use with Arcade' ./make.py html + +To enable it on your system: + +1. cd to your repo root +2. `touch .ENABLE_DEVMACHINE_SPHINX_STATIC_FIX` + +Removal requires: + +1. Sphinx 8.1.4 or another version ships the fixes: + + * https://github.com/sphinx-doc/sphinx/pull/13236 + * https://github.com/sphinx-doc/sphinx/issues/181 + +2. We verify it as compatible with Arcade's dependencies + + +""" + +import sys +import logging +from pathlib import Path +from sphinx import __version__ as sphinx_version + +UTIL_DIR = Path(__file__).parent.resolve() +REPO_ROOT = UTIL_DIR.parent.resolve() +# Ensure we get utility & Arcade imports first +sys.path.insert(0, str(REPO_ROOT)) + +log = logging.getLogger(__name__) + +DOC_DIR = REPO_ROOT / "doc" +STATIC_SOURCE_DIR = DOC_DIR / "_static" + +ENABLE_DEVMACHINE_SPHINX_STATIC_FIX = REPO_ROOT / ".ENABLE_DEVMACHINE_SPHINX_STATIC_FIX" + +BUILD_DIR = REPO_ROOT / "build" +BUILD_HTML_DIR = BUILD_DIR / "html" +BUILD_STATIC_DIR = BUILD_HTML_DIR / "_static" + + +STATIC_CSS_DIR = STATIC_SOURCE_DIR / "css" +force_copy_on_change = { # pending: sphinx >= 8.1.4 + source_file: BUILD_STATIC_DIR / f"css/{source_file.name}" + for source_file in STATIC_CSS_DIR.glob("*.css") +} + +def force_sync(src, dest, dry: bool = False): + if sphinx_version >= '8.1.4': + log.warning( + 'Sphinx >= 8.1.4 may patch broken _static copy\n' + ' (see https://github.com/sphinx-doc/sphinx/issues/1810)') + try: + if src.read_text() != dest.read_text(): + if dry: + log.info(f" DRY : {src} was out of date, but dry run left it as-is!") + # shutil.copyfile(src, dest) + else: + log.info(f" SYNC: {src} was out of date!") + + else: + log.info(f" SKIP: {src} is current!") + except Exception as e: + log.error(f" FAIL: {src} failed: {e}") + raise e + + +def main(): + if not ENABLE_DEVMACHINE_SPHINX_STATIC_FIX.exists(): + log.info(f"SKIP: Force-sync found no {ENABLE_DEVMACHINE_SPHINX_STATIC_FIX} file!") + elif BUILD_HTML_DIR.exists(): + log.info(f"SYNC: Force-sync enable file found") + for src, dest in force_copy_on_change.items(): + force_sync(src, dest) + else: + log.info("Skipping force-sync due to no build dir") + + +if __name__ == "__main__": + main() From d739d28176321349b25675caefc5e057f59fc873 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sun, 19 Jan 2025 16:49:22 -0500 Subject: [PATCH 4/8] Remove extraneous commits + add annotations and docstrings --- doc/conf.py | 12 ++---- util/sphinx_static_file_temp_fix.py | 60 +++++++++++++++++++++-------- 2 files changed, 48 insertions(+), 24 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 3177698e2b..e576ade07a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,8 +1,6 @@ #!/usr/bin/env python """Sphinx configuration file""" from __future__ import annotations - -import shutil from functools import cache import logging from pathlib import Path @@ -29,21 +27,16 @@ logging.basicConfig(level=logging.INFO) HERE = Path(__file__).resolve() -DOC_DIR = HERE.parent -REPO_LOCAL_ROOT = DOC_DIR.parent +REPO_LOCAL_ROOT = HERE.parent.parent ARCADE_MODULE = REPO_LOCAL_ROOT / "arcade" UTIL_DIR = REPO_LOCAL_ROOT / "util" -BUILD_DIR = REPO_LOCAL_ROOT / "build" -BUILD_HTML_DIR = BUILD_DIR / "html" - 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)) @@ -52,7 +45,6 @@ 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. @@ -97,6 +89,8 @@ def run_util(filename, run_name="__main__", init_globals=None): runpy.run_path(full_str, **kwargs) +# Temp fix for Sphinx not copying static files # pending: post-3.0 refactor +# Enable by creating a .ENABLE_DEVMACHINE_SPHINX_STATIC_FIX run_util("sphinx_static_file_temp_fix.py") # Make thumbnails for the example code screenshots diff --git a/util/sphinx_static_file_temp_fix.py b/util/sphinx_static_file_temp_fix.py index 4f0434b44b..b08d749de4 100644 --- a/util/sphinx_static_file_temp_fix.py +++ b/util/sphinx_static_file_temp_fix.py @@ -1,28 +1,47 @@ #!/usr/bin/env python3 """ -A quick, ugly fix for a broken static file handler. +Gets 3.0 out the door by temp fixing Sphinx rebuild not copying CSS. -This runs sync over static folders entries crucial for web dev -which Sphinx <= 8.1.3 does not properly handle due to early exit -checks. Keep the following in mind: +IMPORTANT: ONLY LOCAL DEVELOPER MACHINES NEED THIS! -1. It is not tested to work with sphinx-autobuild or ./make.py serve -2. It was created for use with Arcade' ./make.py html +## Who should use this? -To enable it on your system: +Does `./make.py html` fail to copy modified CSS files on your dev machine? -1. cd to your repo root -2. `touch .ENABLE_DEVMACHINE_SPHINX_STATIC_FIX` +| Behavior | Action | +|---------------------------|------------------------------------| +| I use `./make.py serve`. | Don't worry about it | +| It won't copy CSS changes.| Keep reading | +| Works on my machine | Check if you use `./make.py serve` | -Removal requires: +## How do I use this? -1. Sphinx 8.1.4 or another version ships the fixes: +1. `cd` to the repo root +2. `touch .ENABLE_DEVMACHINE_SPHINX_STATIC_FIX` +3. `./make.py html` with working CSS change updates copying - * https://github.com/sphinx-doc/sphinx/pull/13236 - * https://github.com/sphinx-doc/sphinx/issues/181 +## When should I be careful? -2. We verify it as compatible with Arcade's dependencies +Keep the following in mind: +1. It is not tested to work with sphinx-autobuild or `./make.py serve` +2. It was created for use with Arcade's `./make.py html` +3. No real config options atm (PRs welcome) + +## What did Sphinx break this time? + +1. Sphinx has a long-standing bug which fails to copy static files + https://github.com/sphinx-doc/sphinx/issues/181 + +2. They only merged a PR for this into their dev branch on Jan 13, 2025: + https://github.com/sphinx-doc/sphinx/pull/13236 + +3. No, Arcade 3.0 **will not wait** for the following: + + 1. Sphinx 3.1.4+ to ship the fix for the problem + 2. Themes to become compatible + 3. Plugins to become compatible + 4. Our customizations to be tested with all of the above """ @@ -33,6 +52,7 @@ UTIL_DIR = Path(__file__).parent.resolve() REPO_ROOT = UTIL_DIR.parent.resolve() + # Ensure we get utility & Arcade imports first sys.path.insert(0, str(REPO_ROOT)) @@ -54,7 +74,17 @@ for source_file in STATIC_CSS_DIR.glob("*.css") } -def force_sync(src, dest, dry: bool = False): + +def force_sync(src: Path, dest: Path, dry: bool = False) -> None: + """Sync a single file from ``src`` to ``dest``. + + Caveats: + + 1. Assumes both are `pathlib.Path` instances + 2. Assumes both are small + 3. Fails hard when a file isn't found + + """ if sphinx_version >= '8.1.4': log.warning( 'Sphinx >= 8.1.4 may patch broken _static copy\n' From 9137481b13d20f066f4fcfa6ac535c9a0ebc7158 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sun, 19 Jan 2025 16:55:33 -0500 Subject: [PATCH 5/8] Fix broken URL link in docstring --- util/sphinx_static_file_temp_fix.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/util/sphinx_static_file_temp_fix.py b/util/sphinx_static_file_temp_fix.py index b08d749de4..7f50269697 100644 --- a/util/sphinx_static_file_temp_fix.py +++ b/util/sphinx_static_file_temp_fix.py @@ -31,14 +31,14 @@ ## What did Sphinx break this time? 1. Sphinx has a long-standing bug which fails to copy static files - https://github.com/sphinx-doc/sphinx/issues/181 + https://github.com/sphinx-doc/sphinx/issues/1810 -2. They only merged a PR for this into their dev branch on Jan 13, 2025: +2. The fix is slated for 8.2.0 and the fix PR merged on Jan 13, 2025: https://github.com/sphinx-doc/sphinx/pull/13236 3. No, Arcade 3.0 **will not wait** for the following: - 1. Sphinx 3.1.4+ to ship the fix for the problem + 1. Sphinx 3.2.0 to ship the fix for the problem 2. Themes to become compatible 3. Plugins to become compatible 4. Our customizations to be tested with all of the above From edd1fd9b5ba990471c53db3899a765fc9060b034 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sun, 19 Jan 2025 17:00:46 -0500 Subject: [PATCH 6/8] Extra safety for when we notice we shouldn't run --- util/sphinx_static_file_temp_fix.py | 1 + 1 file changed, 1 insertion(+) diff --git a/util/sphinx_static_file_temp_fix.py b/util/sphinx_static_file_temp_fix.py index 7f50269697..b4d73e4d41 100644 --- a/util/sphinx_static_file_temp_fix.py +++ b/util/sphinx_static_file_temp_fix.py @@ -107,6 +107,7 @@ def force_sync(src: Path, dest: Path, dry: bool = False) -> None: def main(): if not ENABLE_DEVMACHINE_SPHINX_STATIC_FIX.exists(): log.info(f"SKIP: Force-sync found no {ENABLE_DEVMACHINE_SPHINX_STATIC_FIX} file!") + return elif BUILD_HTML_DIR.exists(): log.info(f"SYNC: Force-sync enable file found") for src, dest in force_copy_on_change.items(): From 36949c97f5e1e9e0983e12c7f7d4df108227c0cd Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sun, 19 Jan 2025 23:19:31 -0500 Subject: [PATCH 7/8] Fix some pathing stuff + test with ./make.py serve * Fix paths * Update top-of-file docstring --- util/sphinx_static_file_temp_fix.py | 37 ++++++++++++++--------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/util/sphinx_static_file_temp_fix.py b/util/sphinx_static_file_temp_fix.py index b4d73e4d41..8716419c7f 100644 --- a/util/sphinx_static_file_temp_fix.py +++ b/util/sphinx_static_file_temp_fix.py @@ -6,13 +6,8 @@ ## Who should use this? -Does `./make.py html` fail to copy modified CSS files on your dev machine? - -| Behavior | Action | -|---------------------------|------------------------------------| -| I use `./make.py serve`. | Don't worry about it | -| It won't copy CSS changes.| Keep reading | -| Works on my machine | Check if you use `./make.py serve` | +If `./make.py clean` seems like the only way to get `./make.py html` or +`./make.py serve` to serve your modified CSS, then yes, it's for you. ## How do I use this? @@ -24,11 +19,14 @@ Keep the following in mind: -1. It is not tested to work with sphinx-autobuild or `./make.py serve` -2. It was created for use with Arcade's `./make.py html` -3. No real config options atm (PRs welcome) +1. It is a temp fix which *seems* to work with both: + + * `./make.py html` + * `./make.py serve` + +3. No real config options other on/off via file presence -## What did Sphinx break this time? +## What's Broken in Sphinx? 1. Sphinx has a long-standing bug which fails to copy static files https://github.com/sphinx-doc/sphinx/issues/1810 @@ -64,13 +62,13 @@ ENABLE_DEVMACHINE_SPHINX_STATIC_FIX = REPO_ROOT / ".ENABLE_DEVMACHINE_SPHINX_STATIC_FIX" BUILD_DIR = REPO_ROOT / "build" -BUILD_HTML_DIR = BUILD_DIR / "html" +BUILD_HTML_DIR = BUILD_DIR / "html" / "doc" BUILD_STATIC_DIR = BUILD_HTML_DIR / "_static" - +BUILD_CSS_DIR = BUILD_STATIC_DIR / "css" STATIC_CSS_DIR = STATIC_SOURCE_DIR / "css" force_copy_on_change = { # pending: sphinx >= 8.1.4 - source_file: BUILD_STATIC_DIR / f"css/{source_file.name}" + source_file: BUILD_CSS_DIR / source_file.name for source_file in STATIC_CSS_DIR.glob("*.css") } @@ -108,12 +106,13 @@ def main(): if not ENABLE_DEVMACHINE_SPHINX_STATIC_FIX.exists(): log.info(f"SKIP: Force-sync found no {ENABLE_DEVMACHINE_SPHINX_STATIC_FIX} file!") return - elif BUILD_HTML_DIR.exists(): - log.info(f"SYNC: Force-sync enable file found") - for src, dest in force_copy_on_change.items(): - force_sync(src, dest) - else: + elif not BUILD_HTML_DIR.exists(): log.info("Skipping force-sync due to no build dir") + return + + log.info(f"SYNC: Force-sync enable file found") + for src, dest in force_copy_on_change.items(): + force_sync(src, dest) if __name__ == "__main__": From 10a9f89a394396b61d2db599878cfe4ec2653da1 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Mon, 20 Jan 2025 17:03:10 -0500 Subject: [PATCH 8/8] Fix dirs --- util/sphinx_static_file_temp_fix.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/util/sphinx_static_file_temp_fix.py b/util/sphinx_static_file_temp_fix.py index 8716419c7f..2a8593ae89 100644 --- a/util/sphinx_static_file_temp_fix.py +++ b/util/sphinx_static_file_temp_fix.py @@ -62,7 +62,7 @@ ENABLE_DEVMACHINE_SPHINX_STATIC_FIX = REPO_ROOT / ".ENABLE_DEVMACHINE_SPHINX_STATIC_FIX" BUILD_DIR = REPO_ROOT / "build" -BUILD_HTML_DIR = BUILD_DIR / "html" / "doc" +BUILD_HTML_DIR = BUILD_DIR / "html" BUILD_STATIC_DIR = BUILD_HTML_DIR / "_static" BUILD_CSS_DIR = BUILD_STATIC_DIR / "css" @@ -107,7 +107,7 @@ def main(): log.info(f"SKIP: Force-sync found no {ENABLE_DEVMACHINE_SPHINX_STATIC_FIX} file!") return elif not BUILD_HTML_DIR.exists(): - log.info("Skipping force-sync due to no build dir") + log.info(f"SKIP: {BUILD_HTML_DIR} does not exist yet.") return log.info(f"SYNC: Force-sync enable file found")