From 83344c4837cdbe4ec5e05b925acd9a10fbb83415 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 09:28:19 +0000 Subject: [PATCH 1/3] Make docs build independent of network and builder speed Read the Docs builds (e.g. for #459) fail intermittently while executing the docs notebooks, unrelated to the PR under review: - tabular-data.ipynb downloads the California housing dataset via fetch_california_housing at build time; a failed or partial download aborts the build. - quick-start.ipynb runs %timeit on resample_iterations with automatic loop counts (17.6 s locally), close to the 60 s nbsphinx cell timeout on slower RTD builders. Generate a synthetic house prices dataset instead of downloading, bound %timeit to one loop per repeat, raise nbsphinx_timeout to 300 s, and block network access in the docs notebooks CI job so a notebook that downloads data fails in CI instead of only on RTD. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MvmKb6kjQzUUXx7GBEvDo4 --- .github/workflows/xskillscore_testing.yml | 10 + CHANGELOG.rst | 6 + docs/source/conf.py | 3 +- docs/source/quick-start.ipynb | 4 +- docs/source/tabular-data.ipynb | 223 +--------------------- 5 files changed, 29 insertions(+), 217 deletions(-) diff --git a/.github/workflows/xskillscore_testing.yml b/.github/workflows/xskillscore_testing.yml index 9aa81fa0..21bd248e 100644 --- a/.github/workflows/xskillscore_testing.yml +++ b/.github/workflows/xskillscore_testing.yml @@ -119,6 +119,16 @@ jobs: run: | python -m pip install --no-deps -e . - name: Test notebooks in docs + # Route HTTP(S) to a dead proxy so notebooks that download data at build + # time fail here, not only intermittently on Read the Docs. + # intersphinx inventories then fail too, which only emits warnings. + env: + HTTP_PROXY: http://127.0.0.1:9 + HTTPS_PROXY: http://127.0.0.1:9 + http_proxy: http://127.0.0.1:9 + https_proxy: http://127.0.0.1:9 + NO_PROXY: "" + no_proxy: "" run: | pushd docs nbstripout source/*.ipynb diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 79458666..36a554a6 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -39,6 +39,12 @@ Documentation ``__init__``. (:pr:`451`) `Aaron Spring`_ - Added a `Context7 `_ documentation badge to the README and docs landing page. (:pr:`451`) `Aaron Spring`_ +- Made the Read the Docs build independent of the network and of builder speed: + the tabular data notebook now generates a synthetic house prices dataset instead + of downloading the California housing data with ``fetch_california_housing``, and + the ``%timeit`` cell in the quick start runs once per repeat. ``nbsphinx_timeout`` + is raised to 300 s per cell. The docs notebooks CI job now builds with network + access blocked, so notebooks that download data fail there. `Aaron Spring`_ Internal Changes ~~~~~~~~~~~~~~~~ diff --git a/docs/source/conf.py b/docs/source/conf.py index 5e06f03b..2c843d8e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -63,7 +63,8 @@ autodoc_typehints = "none" -nbsphinx_timeout = 60 +# per cell; Read the Docs builders are slower than GitHub Actions runners +nbsphinx_timeout = 300 nbsphinx_execute = "always" autosummary_generate = True diff --git a/docs/source/quick-start.ipynb b/docs/source/quick-start.ipynb index aeba73aa..72dbeebe 100644 --- a/docs/source/quick-start.ipynb +++ b/docs/source/quick-start.ipynb @@ -1336,9 +1336,9 @@ "source": [ "# resample with replacement in that one dimension\n", "iterations = 100\n", - "%timeit f_r = xs.resampling.resample_iterations(f, iterations, 'member', replace=True)\n", + "%timeit -n 1 -r 3 f_r = xs.resampling.resample_iterations(f, iterations, 'member', replace=True)\n", "# resample_iterations_idx is much (50x) faster because it involves no loops\n", - "%timeit f_r = xs.resampling.resample_iterations_idx(f, iterations, 'member', replace=True)\n", + "%timeit -n 1 -r 3 f_r = xs.resampling.resample_iterations_idx(f, iterations, 'member', replace=True)\n", "# but both do the same resampling" ] }, diff --git a/docs/source/tabular-data.ipynb b/docs/source/tabular-data.ipynb index 83645923..d1d3da52 100644 --- a/docs/source/tabular-data.ipynb +++ b/docs/source/tabular-data.ipynb @@ -29,7 +29,6 @@ "import numpy as np\n", "import pandas as pd\n", "import xskillscore as xs\n", - "from sklearn.datasets import fetch_california_housing\n", "from sklearn.metrics import mean_squared_error\n", "\n", "np.random.seed(seed=42)" @@ -39,7 +38,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## California house prices dataset" + "## House prices dataset" ] }, { @@ -48,224 +47,20 @@ "source": [ "A small example is to take a dataset and evaluate the model according to a field (column).\n", "\n", - "Load the California house prices dataset:" + "Create a synthetic house prices dataset, where the price `y` increases with the\n", + "average number of rooms `AveRooms`. The data is generated locally so the\n", + "documentation builds without downloading anything:" ] }, { "cell_type": "code", - "execution_count": 3, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
MedIncHouseAgeAveRoomsAveBedrmsPopulationAveOccupLatitudeLongitudey
08.325241.07.01.023810322.02.55555637.88-122.234.526
18.301421.06.00.9718802401.02.10984237.86-122.223.585
27.257452.08.01.073446496.02.80226037.85-122.243.521
35.643152.06.01.073059558.02.54794537.85-122.253.413
43.846252.06.01.081081565.02.18146737.85-122.253.422
..............................
206351.560325.05.01.133333845.02.56060639.48-121.090.781
206362.556818.06.01.315789356.03.12280739.49-121.210.771
206371.700017.05.01.1200921007.02.32563539.43-121.220.923
206381.867218.05.01.171920741.02.12320939.43-121.320.847
206392.388616.05.01.1622641387.02.61698139.37-121.240.894
\n", - "

20640 rows × 9 columns

\n", - "
" - ], - "text/plain": [ - " MedInc HouseAge AveRooms AveBedrms Population AveOccup Latitude \\\n", - "0 8.3252 41.0 7.0 1.023810 322.0 2.555556 37.88 \n", - "1 8.3014 21.0 6.0 0.971880 2401.0 2.109842 37.86 \n", - "2 7.2574 52.0 8.0 1.073446 496.0 2.802260 37.85 \n", - "3 5.6431 52.0 6.0 1.073059 558.0 2.547945 37.85 \n", - "4 3.8462 52.0 6.0 1.081081 565.0 2.181467 37.85 \n", - "... ... ... ... ... ... ... ... \n", - "20635 1.5603 25.0 5.0 1.133333 845.0 2.560606 39.48 \n", - "20636 2.5568 18.0 6.0 1.315789 356.0 3.122807 39.49 \n", - "20637 1.7000 17.0 5.0 1.120092 1007.0 2.325635 39.43 \n", - "20638 1.8672 18.0 5.0 1.171920 741.0 2.123209 39.43 \n", - "20639 2.3886 16.0 5.0 1.162264 1387.0 2.616981 39.37 \n", - "\n", - " Longitude y \n", - "0 -122.23 4.526 \n", - "1 -122.22 3.585 \n", - "2 -122.24 3.521 \n", - "3 -122.25 3.413 \n", - "4 -122.25 3.422 \n", - "... ... ... \n", - "20635 -121.09 0.781 \n", - "20636 -121.21 0.771 \n", - "20637 -121.22 0.923 \n", - "20638 -121.32 0.847 \n", - "20639 -121.24 0.894 \n", - "\n", - "[20640 rows x 9 columns]" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ - "housing = fetch_california_housing(as_frame=True)\n", - "df = housing.frame\n", - "df[\"AveRooms\"] = df[\"AveRooms\"].round()\n", - "df = df.rename(columns={\"MedHouseVal\": \"y\"})\n", + "n = 20_000\n", + "df = pd.DataFrame({\"AveRooms\": np.random.randint(1, 11, size=n).astype(float)})\n", + "df[\"y\"] = 0.5 + 0.3 * df[\"AveRooms\"] + np.random.gamma(2.0, 0.5, size=n)\n", "df" ] }, From 204525077c49f8734f28bb9b7000c908c4ef9078 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 12:45:32 +0000 Subject: [PATCH 2/3] Drop CHANGELOG entry for docs build fix Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MvmKb6kjQzUUXx7GBEvDo4 --- CHANGELOG.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 36a554a6..79458666 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -39,12 +39,6 @@ Documentation ``__init__``. (:pr:`451`) `Aaron Spring`_ - Added a `Context7 `_ documentation badge to the README and docs landing page. (:pr:`451`) `Aaron Spring`_ -- Made the Read the Docs build independent of the network and of builder speed: - the tabular data notebook now generates a synthetic house prices dataset instead - of downloading the California housing data with ``fetch_california_housing``, and - the ``%timeit`` cell in the quick start runs once per repeat. ``nbsphinx_timeout`` - is raised to 300 s per cell. The docs notebooks CI job now builds with network - access blocked, so notebooks that download data fail there. `Aaron Spring`_ Internal Changes ~~~~~~~~~~~~~~~~ From 9e52bbd5341a1736a43bc8edbdd1c18db0c2c777 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 12:58:18 +0000 Subject: [PATCH 3/3] Fix invalid workflow: env keys are case-insensitive GitHub Actions rejected xskillscore_testing.yml because HTTP_PROXY and http_proxy (and the HTTPS/NO_PROXY pairs) are duplicate keys in a case-insensitive env mapping, so no test jobs ran. Python's urllib and requests honour the uppercase names, so keep only those. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MvmKb6kjQzUUXx7GBEvDo4 --- .github/workflows/xskillscore_testing.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/xskillscore_testing.yml b/.github/workflows/xskillscore_testing.yml index 21bd248e..04fcf9d4 100644 --- a/.github/workflows/xskillscore_testing.yml +++ b/.github/workflows/xskillscore_testing.yml @@ -125,10 +125,7 @@ jobs: env: HTTP_PROXY: http://127.0.0.1:9 HTTPS_PROXY: http://127.0.0.1:9 - http_proxy: http://127.0.0.1:9 - https_proxy: http://127.0.0.1:9 NO_PROXY: "" - no_proxy: "" run: | pushd docs nbstripout source/*.ipynb