From b87e04e9ddf26aa8e46c3bca8c7a7ca842d802d6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 26 Oct 2026 13:24:48 +0000 Subject: [PATCH 1/5] Initial plan From 2630d0194569cb43cefbd4f3e035488121a49c01 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 26 Oct 2026 13:26:36 +0000 Subject: [PATCH 2/5] python.yml (build-doc): Do not restore stale Sphinx doctrees cache Co-authored-by: MLopez-Ibanez <2620021+MLopez-Ibanez@users.noreply.github.com> --- .github/workflows/python.yml | 7 ------- 1 file changed, 7 deletions(-) diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml index 7ee6898a5..ba517064f 100644 --- a/.github/workflows/python.yml +++ b/.github/workflows/python.yml @@ -141,13 +141,6 @@ jobs: run: python3 -m pip install .[docs] working-directory: python - - name: Cache intersphinx inventories - uses: actions/cache@v5 - with: - path: python/doc/_build/doctrees/ - key: intersphinx-${{ hashFiles('python/doc/source/conf.py') }} - restore-keys: intersphinx- - - name: Build the docs 🔧 run: | make -C doc html From d992ebdc8460499562baf5fbc0b8ef50c045cb86 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 26 Oct 2026 13:43:08 +0000 Subject: [PATCH 3/5] Cache only intersphinx inventories in the docs job Co-authored-by: MLopez-Ibanez <2620021+MLopez-Ibanez@users.noreply.github.com> --- .github/workflows/python.yml | 7 ++++++ python/.gitignore | 1 + python/doc/source/conf.py | 48 ++++++++++++++++++++++++++++++------ 3 files changed, 48 insertions(+), 8 deletions(-) diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml index ba517064f..e14dff9f4 100644 --- a/.github/workflows/python.yml +++ b/.github/workflows/python.yml @@ -141,6 +141,13 @@ jobs: run: python3 -m pip install .[docs] working-directory: python + - name: Cache intersphinx inventories + uses: actions/cache@v5 + with: + path: python/doc/_intersphinx_cache/ + key: intersphinx-${{ hashFiles('python/doc/source/conf.py') }} + restore-keys: intersphinx- + - name: Build the docs 🔧 run: | make -C doc html diff --git a/python/.gitignore b/python/.gitignore index 7c9af9f41..431040d39 100644 --- a/python/.gitignore +++ b/python/.gitignore @@ -75,6 +75,7 @@ instance/ # Sphinx documentation doc/_build/ +doc/_intersphinx_cache/ doc/jupyter_execute/ doc/source/reference/generated/ doc/source/auto_examples diff --git a/python/doc/source/conf.py b/python/doc/source/conf.py index 4a80c3dd6..0d297703d 100644 --- a/python/doc/source/conf.py +++ b/python/doc/source/conf.py @@ -242,15 +242,47 @@ def setup(app): # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" +_intersphinx_urls = { + "matplotlib": "https://matplotlib.org/stable", + "mooplot": "https://multi-objective.github.io/mooplot/python", + # "neps": "https://numpy.org/neps/", + "numpy": "https://numpy.org/doc/stable", + "nx-guides": "https://networkx.org/nx-guides", + "pandas": "https://pandas.pydata.org/pandas-docs/stable", + "python": "https://docs.python.org/3", + "scipy": "https://scipy.github.io/devdocs", +} + +# Inventories are downloaded to this directory, which is the only thing cached +# in CI. A cached inventory is used until it is older than +# intersphinx_cache_limit days; otherwise, Sphinx fetches it from the URL. +_intersphinx_cache_dir = os.path.join( + os.path.dirname(os.path.abspath(__file__)), "..", "_intersphinx_cache" +) + + +def _cached_inventory(name, url): + import time + import urllib.request + + path = os.path.join(_intersphinx_cache_dir, name + ".inv") + max_age = 90 * 24 * 3600 # seconds + if os.path.exists(path) and time.time() - os.path.getmtime(path) < max_age: + return path + try: + os.makedirs(_intersphinx_cache_dir, exist_ok=True) + with urllib.request.urlopen(url + "/objects.inv", timeout=15) as r: + data = r.read() + with open(path, "wb") as f: + f.write(data) + return path + except Exception: + return None # Sphinx will fetch it from the URL + + intersphinx_mapping = { - "matplotlib": ("https://matplotlib.org/stable", None), - "mooplot": ("https://multi-objective.github.io/mooplot/python", None), - # "neps": ("https://numpy.org/neps/", None), - "numpy": ("https://numpy.org/doc/stable", None), - "nx-guides": ("https://networkx.org/nx-guides", None), - "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None), - "python": ("https://docs.python.org/3", None), - "scipy": ("https://scipy.github.io/devdocs", None), + name: (url, (_cached_inventory(name, url), None)) + for name, url in _intersphinx_urls.items() } intersphinx_timeout = 15 # seconds intersphinx_cache_limit = 90 # days From ad1af0b7d8ab5fddec2b0eb6a76f895f5231132f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 26 Oct 2026 13:48:50 +0000 Subject: [PATCH 4/5] Cache only doctrees/__intersphinx_cache__/ and drop custom caching in conf.py Co-authored-by: MLopez-Ibanez <2620021+MLopez-Ibanez@users.noreply.github.com> --- .github/workflows/python.yml | 2 +- python/.gitignore | 1 - python/doc/source/conf.py | 48 ++++++------------------------------ 3 files changed, 9 insertions(+), 42 deletions(-) diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml index e14dff9f4..77d4e406f 100644 --- a/.github/workflows/python.yml +++ b/.github/workflows/python.yml @@ -144,7 +144,7 @@ jobs: - name: Cache intersphinx inventories uses: actions/cache@v5 with: - path: python/doc/_intersphinx_cache/ + path: python/doc/_build/doctrees/__intersphinx_cache__/ key: intersphinx-${{ hashFiles('python/doc/source/conf.py') }} restore-keys: intersphinx- diff --git a/python/.gitignore b/python/.gitignore index 431040d39..7c9af9f41 100644 --- a/python/.gitignore +++ b/python/.gitignore @@ -75,7 +75,6 @@ instance/ # Sphinx documentation doc/_build/ -doc/_intersphinx_cache/ doc/jupyter_execute/ doc/source/reference/generated/ doc/source/auto_examples diff --git a/python/doc/source/conf.py b/python/doc/source/conf.py index 0d297703d..4a80c3dd6 100644 --- a/python/doc/source/conf.py +++ b/python/doc/source/conf.py @@ -242,47 +242,15 @@ def setup(app): # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" -_intersphinx_urls = { - "matplotlib": "https://matplotlib.org/stable", - "mooplot": "https://multi-objective.github.io/mooplot/python", - # "neps": "https://numpy.org/neps/", - "numpy": "https://numpy.org/doc/stable", - "nx-guides": "https://networkx.org/nx-guides", - "pandas": "https://pandas.pydata.org/pandas-docs/stable", - "python": "https://docs.python.org/3", - "scipy": "https://scipy.github.io/devdocs", -} - -# Inventories are downloaded to this directory, which is the only thing cached -# in CI. A cached inventory is used until it is older than -# intersphinx_cache_limit days; otherwise, Sphinx fetches it from the URL. -_intersphinx_cache_dir = os.path.join( - os.path.dirname(os.path.abspath(__file__)), "..", "_intersphinx_cache" -) - - -def _cached_inventory(name, url): - import time - import urllib.request - - path = os.path.join(_intersphinx_cache_dir, name + ".inv") - max_age = 90 * 24 * 3600 # seconds - if os.path.exists(path) and time.time() - os.path.getmtime(path) < max_age: - return path - try: - os.makedirs(_intersphinx_cache_dir, exist_ok=True) - with urllib.request.urlopen(url + "/objects.inv", timeout=15) as r: - data = r.read() - with open(path, "wb") as f: - f.write(data) - return path - except Exception: - return None # Sphinx will fetch it from the URL - - intersphinx_mapping = { - name: (url, (_cached_inventory(name, url), None)) - for name, url in _intersphinx_urls.items() + "matplotlib": ("https://matplotlib.org/stable", None), + "mooplot": ("https://multi-objective.github.io/mooplot/python", None), + # "neps": ("https://numpy.org/neps/", None), + "numpy": ("https://numpy.org/doc/stable", None), + "nx-guides": ("https://networkx.org/nx-guides", None), + "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None), + "python": ("https://docs.python.org/3", None), + "scipy": ("https://scipy.github.io/devdocs", None), } intersphinx_timeout = 15 # seconds intersphinx_cache_limit = 90 # days From 375649f416b423509275c120d99ddd19a92dc4c2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 26 Oct 2026 15:37:14 +0000 Subject: [PATCH 5/5] docs: require Sphinx>=9 for on-disk intersphinx inventory cache Co-authored-by: MLopez-Ibanez <2620021+MLopez-Ibanez@users.noreply.github.com> --- python/pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/pyproject.toml b/python/pyproject.toml index e3672ff31..f36004a7d 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -70,7 +70,7 @@ docs = [ "plotly", "pydata-sphinx-theme>=0.16", "seaborn", - "sphinx>=6", + "sphinx>=9", "sphinx-autodoc-typehints", "sphinx-copybutton", "sphinx-design",