Do not fail because of Linkcheck, add ignored links (#304)

### What kind of change does this PR introduce? * Added some links to ignore * Configured ReadTheDocs to not fail build if Linkcheck step fails * Moved notebooks into an "Examples" section ### Does this PR introduce a breaking change? No.
Ouranosinc · Dec 15, 2023 · fded6b9 · fded6b9
2 parents e461ccf + 5921aaa
commit fded6b9
Show file tree

Hide file tree

Showing 13 changed files with 37 additions and 53 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -79,6 +79,7 @@ repos:
     hooks:
       - id: nbstripout
         files: ".ipynb"
+        args: [ '--extra-keys', 'metadata.kernelspec' ]
   - repo: https://github.com/Yelp/detect-secrets
     rev: v1.4.0
     hooks:

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -17,7 +17,7 @@ build:
       - pip install . --no-deps
     pre_build:
       - sphinx-apidoc -o docs/apidoc --private --module-first xscen
-      - env SKIP_NOTEBOOKS=1 sphinx-build -b linkcheck docs/ _build/linkcheck
+      - env SKIP_NOTEBOOKS=1 sphinx-build -b linkcheck docs/ _build/linkcheck || true
 #    post_build:
 #      - rm -rf docs/notebooks/_data
 

diff --git a/CHANGES.rst b/CHANGES.rst
@@ -72,6 +72,7 @@ Internal changes
 * Linting checks now examine the testing folder, function complexity, and alphabetical order of `__all__` lists. (:pull:`292`).
 * ``publish_release_notes`` now uses better logic for finding and reformatting the `CHANGES.rst` file. (:pull:`292`).
 * ``bump2version`` version-bumping utility was replaced by ``bump-my-version``. (:pull:`292`).
+* Documentation build checks no longer fail due to broken external links; Notebooks are now nested and numbered. (:pull:`304`).
 
 v0.7.1 (2023-08-23)
 -------------------

diff --git a/docs/conf.py b/docs/conf.py
@@ -132,6 +132,8 @@
 
 linkcheck_ignore = [
     r"https://github.com/Ouranosinc/xscen/(pull|issue).*",  # too labourious to fully check
+    r"https://rmets.onlinelibrary.wiley.com/doi/10.1002/qj.3803",  # Error 403: Forbidden
+    r"https://library.wmo.int/idurl/4/56300",  # HTTPconnectionPool error
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -174,6 +176,7 @@
     "_build",
     "Thumbs.db",
     ".DS_Store",
+    "notebooks/global_tas_average_obs.ipynb"
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.

diff --git a/docs/index.rst b/docs/index.rst
@@ -27,12 +27,7 @@ Features
     readme
     installation
     goodtoknow
-    notebooks/1_catalog
-    notebooks/2_getting_started
-    notebooks/3_diagnostics
-    notebooks/4_ensemble_reduction
-    notebooks/5_warminglevels
-    notebooks/6_config
+    notebooks/index
     columns
     templates
     api

diff --git a/docs/notebooks/1_catalog.ipynb b/docs/notebooks/1_catalog.ipynb
@@ -1136,11 +1136,6 @@
    "lastCommId": null,
    "lastKernelId": null
   },
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",

diff --git a/docs/notebooks/2_getting_started.ipynb b/docs/notebooks/2_getting_started.ipynb
@@ -1450,11 +1450,6 @@
    "lastCommId": null,
    "lastKernelId": null
   },
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",

diff --git a/docs/notebooks/3_diagnostics.ipynb b/docs/notebooks/3_diagnostics.ipynb
@@ -474,11 +474,6 @@
    "lastCommId": null,
    "lastKernelId": null
   },
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",

diff --git a/docs/notebooks/4_ensemble_reduction.ipynb b/docs/notebooks/4_ensemble_reduction.ipynb
@@ -152,11 +152,6 @@
    "lastCommId": null,
    "lastKernelId": null
   },
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",

diff --git a/docs/notebooks/5_warminglevels.ipynb b/docs/notebooks/5_warminglevels.ipynb
@@ -473,11 +473,6 @@
   }
  ],
  "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",

diff --git a/docs/notebooks/6_config.ipynb b/docs/notebooks/6_config.ipynb
@@ -368,11 +368,6 @@
   }
  ],
  "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",

diff --git a/docs/notebooks/GlobalTasAverageObs.ipynb → docs/notebooks/global_tas_average_obs.ipynb b/docs/notebooks/GlobalTasAverageObs.ipynb → docs/notebooks/global_tas_average_obs.ipynb
@@ -32,6 +32,8 @@
     "import sys\n",
     "\n",
     "os.environ[\"ESMFMKFILE\"] = os.path.join(sys.prefix, \"lib\", \"esmf.mk\")\n",
+    "from datetime import datetime, timedelta\n",
+    "\n",
     "import dask\n",
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
@@ -90,7 +92,7 @@
    "id": "90fb65b3-1f30-4983-8564-4f3ce0d46678",
    "metadata": {},
    "source": [
-    "## Berkeley Earth\n",
+    "### Berkeley Earth\n",
     "Rohde, R. A.; Hausfather, Z. The Berkeley Earth Land/Ocean Temperature Record. Earth System Science Data 2020, 12, 3469–3479. https://doi.org/10.5194/essd-12-3469-2020.\n",
     "\n",
     "The annual summary of the Global Monthly Averages from 1850 to preset is available online as text file. It comes as an anomaly relative to the 1951-1980 average, which is given directly in the header of the text file. We have the choice of using temperature above or below sea ice for the ocean component. I didn't anything in the WMO recommendation about this, so we will use the temperature above.\n",
@@ -167,7 +169,7 @@
    "id": "ecf5d136-8bad-484e-ab0d-9aa3fa9c23e7",
    "metadata": {},
    "source": [
-    "## GISTEMP v4\n",
+    "### GISTEMP v4\n",
     "GISTEMP Team, 2023: GISS Surface Temperature Analysis (GISTEMP), version 4. NASA Goddard Institute for Space Studies. Dataset accessed 2023-12-06 at https://data.giss.nasa.gov/gistemp/.\n",
     "\n",
     "This dataset comes in a CSV of anomalies relative to 1951-1980.\n"
@@ -201,7 +203,7 @@
    "id": "8baeca9c-caec-4f81-9f99-233694acabb3",
    "metadata": {},
    "source": [
-    "## HadCRUT5\n",
+    "### HadCRUT5\n",
     "Morice, C.P., J.J. Kennedy, N.A. Rayner, J.P. Winn, E. Hogan, R.E. Killick, R.J.H. Dunn, T.J. Osborn, P.D. Jones and I.R. Simpson (in press) An updated assessment of near-surface temperature change from 1850: the HadCRUT5 dataset. Journal of Geophysical Research (Atmospheres) doi:10.1029/2019JD032361 (supporting information). \n",
     "\n",
     "The CSV is an anomaly relative to 1961-1990."
@@ -239,28 +241,29 @@
    "id": "eaa12a90-722c-4a0a-bd21-6db3c1afe73c",
    "metadata": {},
    "source": [
-    "## NOAAGlobalTemp v5\n",
+    "### NOAAGlobalTemp v5\n",
     "R. S. Vose, B. Huang, X. Yin, D. Arndt, D. R. Easterling, J. H. Lawrimore, M. J. Menne, A. Sanchez-Lugo, and H. M. Zhang (2022): NOAA Global Surface Temperature Dataset (NOAAGlobalTemp), Version 5.1 [indicate subset used]. NOAA National Centers for Environmental Information. doi.org/10.25921/2tj4-0e21\n",
     "\n",
-    "Available as a text file as an anomaly relative to 1971-2000."
+    "Available as a text file as an anomaly relative to 1971-2000. The files are updated each month with only the last month kept available."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "997025e1-a300-4c97-bfff-d3d54fa5a956",
+   "id": "86e77060-1b95-4a75-b1bf-230955b172fd",
    "metadata": {
     "tags": []
    },
    "outputs": [],
    "source": [
     "df = pd.read_table(\n",
-    "    \"https://www.ncei.noaa.gov/data/noaa-global-surface-temperature/v5.1/access/timeseries/aravg.ann.land_ocean.90S.90N.v5.1.0.202310.asc\",\n",
+    "    f\"https://www.ncei.noaa.gov/data/noaa-global-surface-temperature/v5.1/access/timeseries/aravg.ann.land_ocean.90S.90N.v5.1.0.202311.asc\",\n",
     "    sep=r\"\\s+\",\n",
     "    usecols=[0, 1],\n",
     "    index_col=0,\n",
     "    names=[\"year\", \"temp\"],\n",
     ")\n",
+    "\n",
     "da = df.temp.to_xarray().assign_attrs(units=\"°C\")\n",
     "\n",
     "daWMO = clean(da)\n",
@@ -273,7 +276,7 @@
    "id": "97a33f82-96e1-4f02-a74e-c7963255669e",
    "metadata": {},
    "source": [
-    "## ERA5\n",
+    "### ERA5\n",
     "Hersbach, H.; Bell, B.; Berrisford, P. et al. The ERA5 global reanalysis. Quarterly Journal of the Royal Meteorological Society 2020, 146 (730), 1999–2049. https://doi.org/10.1002/qj.3803.\n",
     "\n",
     "TODO"
@@ -308,7 +311,7 @@
    "id": "cba799a0-62e6-4795-b086-708ea6556504",
    "metadata": {},
    "source": [
-    "## JRA-55\n",
+    "### JRA-55\n",
     "Ebita, A. et al., 2011, The Japanese 55-year Reanalysis \"JRA-55\": an interim report, SOLA, 7, 149-152.\n",
     "Kobayashi, S. et al., 2015; The JRA-55 Reanalysis: General Specifications and Basic Characteristics, to be published on JMSJ.\n",
     "\n",
@@ -346,7 +349,7 @@
    "id": "c5011372-f958-4175-be0b-af9bebea8daf",
    "metadata": {},
    "source": [
-    "# Combine all"
+    "## Combine all"
    ]
   },
   {
@@ -472,11 +475,6 @@
   }
  ],
  "metadata": {
-  "kernelspec": {
-   "display_name": "xscen-0.7",
-   "language": "python",
-   "name": "xscen-0.7"
-  },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",
@@ -487,7 +485,10 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.12"
+   "version": "3.11.6"
+  },
+  "nbsphinx": {
+   "execute": "never"
   }
  },
  "nbformat": 4,

diff --git a/docs/notebooks/index.rst b/docs/notebooks/index.rst
@@ -0,0 +1,13 @@
+Examples
+========
+
+.. toctree::
+    :maxdepth: 1
+    :numbered:
+
+    1_catalog
+    2_getting_started
+    3_diagnostics
+    4_ensemble_reduction
+    5_warminglevels
+    6_config