From ca6d56c5d8862570b0ae249dbca8e343a24f2a9b Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Fri, 23 Oct 2026 11:00:26 -0400 Subject: [PATCH 1/3] Set up version substitutions from pyproject.toml --- doc/conf.py | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index fbffe2e4e..15608f6b3 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -9,6 +9,7 @@ import re import runpy import sys +import tomllib from docutils import nodes from sphinx.domains.python import PythonDomain @@ -225,6 +226,13 @@ def run_util(filename, run_name="__main__", init_globals=None): # The full version, including alpha/beta/rc tags. release = VERSION +# Variables for our additional substitutions +with open("../pyproject.toml", "rb") as pyproject_file: + pyproject_toml = tomllib.load(pyproject_file) + +min_py_version = pyproject_toml['project']['requires-python'] + + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -236,10 +244,28 @@ def run_util(filename, run_name="__main__", init_globals=None): # directories to ignore when looking for source files. exclude_patterns = [ "_includes/*", - "substitutions.rst", + "substitutions.rst", # built out below "_archive/*", ] +# Set up our substitutions (handy macros) +# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions +_rst_prolog_parts = [] +SUBSTITUTIONS_FILE = Path("substitutions.rst") +if SUBSTITUTIONS_FILE.exists(): + _rst_prolog_parts.append(SUBSTITUTIONS_FILE.read_text()) + + +_rst_prolog_parts.extend([ + f""" + .. |min_py_version| replace:: {min_py_version}" + .. |min_py_fullname| replace:: Python {min_py_version} + .. |min_py_fullname_plus| replace:: Python {min_py_version}+ + """, +]) + +rst_prolog = "\n".join(_rst_prolog_parts) + # The name of the Pygments (syntax highlighting) style to use. pygments_style = "default" # will use "sphinx" or the theme's default From da86c8ccdfab3065b2f8891cb908387dca940dd2 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Fri, 23 Oct 2026 11:12:01 -0400 Subject: [PATCH 2/3] Use substitutions in doc for mininum version --- doc/get_started/install.rst | 4 ++-- doc/programming_guide/gles_raspi_and_sbc.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/get_started/install.rst b/doc/get_started/install.rst index 981314db0..67777eb57 100644 --- a/doc/get_started/install.rst +++ b/doc/get_started/install.rst @@ -19,7 +19,7 @@ Requirements ------------ Arcade requires a desktop, laptop, or compatible Single-Board Computer (SBC) with: -#. Python 3.10 or higher +#. |min_py_fullname_plus| or higher #. Graphics drivers with support for either: * OpenGL 3.3+ * GLES 3.1+ with extensions on SBCs @@ -30,7 +30,7 @@ unsupported. Windows, Linux, and Intel Mac ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Your computer can likely run Arcade if it supports Python 3.10 or higher. +Your computer can likely run Arcade if it supports |min_py_fullname| or higher. In general, even older convertible Windows tablets will work as long as they: diff --git a/doc/programming_guide/gles_raspi_and_sbc.rst b/doc/programming_guide/gles_raspi_and_sbc.rst index 1ab0962d7..94a24ae5e 100644 --- a/doc/programming_guide/gles_raspi_and_sbc.rst +++ b/doc/programming_guide/gles_raspi_and_sbc.rst @@ -114,7 +114,7 @@ requirements may work. Standard Python ^^^^^^^^^^^^^^^ -Arcade requires Python 3.10 or higher. +Arcade requires |min_py_fullname| or higher. In practice, this means running Linux. In theory, it may be possible to run Arcade on an ARM-specific version of Windows, but nobody has tried this before. From e8ab8a42b8d33b6cd1cb5a67fb9cb1bc32060a95 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Fri, 23 Oct 2026 11:31:40 -0400 Subject: [PATCH 3/3] Fix version syncing to use prior substitutions --- doc/conf.py | 35 +++++++++++++++-------------------- doc/get_started/install.rst | 2 +- 2 files changed, 16 insertions(+), 21 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 15608f6b3..c2668abb5 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -226,11 +226,12 @@ def run_util(filename, run_name="__main__", init_globals=None): # The full version, including alpha/beta/rc tags. release = VERSION -# Variables for our additional substitutions + +# Read synced info from pyproject.toml with open("../pyproject.toml", "rb") as pyproject_file: pyproject_toml = tomllib.load(pyproject_file) -min_py_version = pyproject_toml['project']['requires-python'] +min_py_version = pyproject_toml['project']['requires-python'].strip(">=") # The language for content autogenerated by Sphinx. Refer to documentation @@ -248,23 +249,6 @@ def run_util(filename, run_name="__main__", init_globals=None): "_archive/*", ] -# Set up our substitutions (handy macros) -# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions -_rst_prolog_parts = [] -SUBSTITUTIONS_FILE = Path("substitutions.rst") -if SUBSTITUTIONS_FILE.exists(): - _rst_prolog_parts.append(SUBSTITUTIONS_FILE.read_text()) - - -_rst_prolog_parts.extend([ - f""" - .. |min_py_version| replace:: {min_py_version}" - .. |min_py_fullname| replace:: Python {min_py_version} - .. |min_py_fullname_plus| replace:: Python {min_py_version}+ - """, -]) - -rst_prolog = "\n".join(_rst_prolog_parts) # The name of the Pygments (syntax highlighting) style to use. pygments_style = "default" # will use "sphinx" or the theme's default @@ -380,6 +364,7 @@ def run_util(filename, run_name="__main__", init_globals=None): "typing_extensions": ("https://typing-extensions.readthedocs.io/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 = [ @@ -392,11 +377,21 @@ def run_util(filename, run_name="__main__", init_globals=None): ' \n\n' " \n\n" ), + f".. |min_py_version| replace:: {min_py_version}\n" + f".. |min_py_fullname| replace:: Python {min_py_version}\n" + f".. |min_py_fullname_plus| replace:: Python {min_py_version}+" ] + + with open("_includes/links.rst") as f: PROLOG_PARTS.extend(f.readlines()) -rst_prolog = "\n".join(PROLOG_PARTS) +# IMPORTANT: make sure to trim white space or substitutions may cease to exist +rst_prolog = ("\n".join(PROLOG_PARTS)).strip() +print( + "=== rst_prolog: substitutions.rst (if present) + _rst_prolog_parts joined together ===", + rst_prolog, sep="\n", end="\n\n") + def strip_init_return_typehint(app, what, name, obj, options, signature, return_annotation): diff --git a/doc/get_started/install.rst b/doc/get_started/install.rst index 67777eb57..231993b5f 100644 --- a/doc/get_started/install.rst +++ b/doc/get_started/install.rst @@ -19,7 +19,7 @@ Requirements ------------ Arcade requires a desktop, laptop, or compatible Single-Board Computer (SBC) with: -#. |min_py_fullname_plus| or higher +#. |min_py_fullname| or higher #. Graphics drivers with support for either: * OpenGL 3.3+ * GLES 3.1+ with extensions on SBCs