Docs maintenance (#141)

* Update ReadTheDocs build config

Upgraded the OS to Ubuntu 24.04 and updated the Python toolchain to
mambaforge-23.11 in the .readthedocs.yaml file. This ensures compatibility with
the latest environment settings.

* Update Sphinx & optional dependencies version pin

Updated Sphinx and optional dependencies packages pinned versions in
`environment-dev.yaml`, `environment-test.yaml`, and `environment-rtd.yaml` in
preparation for Python 3.13 environment.

* Update broken & redirected docs links from linkcheck

* Update docs example output from Sphinx and pytest

Updated Sphinx build and linkcheck commands example outputs. Also revised the
pytest output to reflect the newer plugin versions and test suite logging
changes.

.readthedocs.yaml

@@ -1,9 +1,9 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "mambaforge-22.9"
+    python: "mambaforge-23.11"
 
 conda:
   environment: envs/environment-rtd.yaml

docs/design_notes/motivation.rst

@@ -57,8 +57,8 @@ that maps especially well to handling NetCDF-4 model results.
 Dask provides a flexible parallel computing framework for operating on extremely large
 datasets without loading them into memory.
 
-.. _converged on: https://pangeo.io/packages.html#why-xarray-and-dask
-.. _Pangeo: https://pangeo.io
+.. _converged on: https://www.pangeo.io/#ecosystem
+.. _Pangeo: https://www.pangeo.io/
 .. _Xarray: https://docs.xarray.dev/en/stable/
 .. _Dask: https://docs.dask.org/en/latest/
 

docs/design_notes/pkg_structure.rst

@@ -58,7 +58,7 @@ Coming soon...
 must be registered,
 and the :py:func:`reshapr.add_command` calls to register the sub-commands.
 
-.. _Click commands group: https://click.palletsprojects.com/en/8.0.x/quickstart/#nesting-commands
+.. _Click commands group: https://click.palletsprojects.com/en/stable/quickstart/#nesting-commands
 
 It is also where configuration of the `structlog logging framework`_ happens.
 All console output from the sub-commands is done via that logging.
@@ -69,7 +69,7 @@ The other modules in :file:`reshapr/cli/` contain the `Click`_ command-line inte
 functions for each of the sub-commands;
 e.g. :py:func:`reshapr.cli.extract.extract`.
 
-.. _Click: https://click.palletsprojects.com
+.. _Click: https://click.palletsprojects.com/en/stable/
 
 
 :file:`reshapr/core/`

docs/examples/prodigy_model_obs_assignment.rst

@@ -42,7 +42,7 @@ The parameters of the SalishSeaCast datasets to be provided to the students are:
    and Richard A. Feely.
    "Marine CO2 patterns in the northern Salish Sea."
    Frontiers in Marine Science 5 (2019): 536.
-   https://www.frontiersin.org/articles/10.3389/fmars.2018.00536/full
+   https://www.frontiersin.org/journals/marine-science/articles/10.3389/fmars.2018.00536/full
 
 
 Execution

docs/installation.rst

@@ -53,7 +53,7 @@ you can create and activate an environment called :kbd:`reshapr` that will have
 all of the Python packages necessary use :py:obj:`Reshapr`,
 and install the package with the commands below.
 
-.. _Conda: https://conda.io/en/latest/
+.. _Conda: https://docs.conda.io/en/latest/
 .. _Miniconda3: https://docs.conda.io/en/latest/miniconda.html
 
 .. code-block:: bash

envs/environment-dev.yaml

@@ -44,9 +44,9 @@ dependencies:
   - tomli
 
   # For documentation
-  - sphinx=7.2.6
-  - sphinx-notfound-page=1.0.0
-  - sphinx-rtd-theme=2.0.0
+  - sphinx==8.1.3
+  - sphinx-notfound-page==1.0.4
+  - sphinx-rtd-theme==3.0.0
 
   - pip:
     # install of Reshapr package in editable mode

envs/environment-rtd.yaml

@@ -11,9 +11,9 @@ dependencies:
   - python=3.12
 
   # Sphinx and extensions
-  - sphinx=7.2.6
-  - sphinx-notfound-page=1.0.0
-  - sphinx-rtd-theme=2.0.0
+  - sphinx==8.1.3
+  - sphinx-notfound-page==1.0.4
+  - sphinx-rtd-theme==3.0.0
 
   # readthedocs build system packages
   - mock

envs/environment-test.yaml

@@ -33,9 +33,9 @@ dependencies:
   - tomli
 
   # For documentation links checking
-  - sphinx=7.2.6
-  - sphinx-notfound-page=1.0.0
-  - sphinx-rtd-theme=2.0.0
+  - sphinx==8.1.3
+  - sphinx-notfound-page==1.0.4
+  - sphinx-rtd-theme==3.0.0
 
   - pip:
     # install Reshapr package in editable mode

envs/requirements.txt

@@ -3,135 +3,135 @@
 # Create/update this file with:
 #   (reshapr-dev)$ python -m pip list --format=freeze >> envs/requirements.txt
 
-alabaster==0.7.16
-anyio==4.3.0
+alabaster==1.0.0
+anyio==4.6.2.post1
 arrow==1.3.0
 Babel==2.14.0
 backports.tarfile==1.0.0
-black==24.4.2
-bokeh==3.4.1
-Bottleneck==1.3.8
+black==24.10.0
+bokeh==3.6.0
+Bottleneck==1.4.2
 Brotli==1.1.0
 cached-property==1.5.2
-certifi==2024.7.4
-cffi==1.16.0
+certifi==2024.8.30
+cffi==1.17.1
 cfgv==3.3.1
-cftime==1.6.3
-charset-normalizer==3.3.2
+cftime==1.6.4
+charset-normalizer==3.4.0
 click==8.1.7
-cloudpickle==3.0.0
+cloudpickle==3.1.0
 colorama==0.4.6
-contourpy==1.2.1
-coverage==7.5.1
-cryptography==43.0.1
-cytoolz==0.12.3
-dask==2024.5.1
-dask-expr==1.1.1
-distlib==0.3.8
-distributed==2024.5.1
-docutils==0.20.1
+contourpy==1.3.0
+coverage==7.6.4
+cryptography==43.0.3
+cytoolz==1.0.0
+dask==2024.10.0
+dask-expr==1.1.16
+distlib==0.3.9
+distributed==2024.10.0
+docutils==0.21.2
 editables==0.5
-exceptiongroup==1.2.0
-filelock==3.14.0
-flox==0.9.7
-fsspec==2024.5.0
+exceptiongroup==1.2.2
+filelock==3.16.1
+flox==0.9.12
+fsspec==2024.10.0
 h11==0.14.0
 h2==4.1.0
-h5netcdf==1.3.0
-h5py==3.11.0
-hatch==1.11.1
-hatchling==1.24.2
+h5netcdf==1.4.0
+h5py==3.12.1
+hatch==1.13.0
+hatchling==1.25.0
 hpack==4.0.0
-httpcore==1.0.5
-httpx==0.27.0
+httpcore==1.0.6
+httpx==0.27.2
 hyperframe==6.0.1
 hyperlink==21.0.0
-identify==2.5.36
-idna==3.7
+identify==2.6.1
+idna==3.10
 imagesize==1.4.1
-importlib_metadata==7.1.0
-importlib_resources==6.4.0
+importlib_metadata==8.5.0
+importlib_resources==6.4.5
 iniconfig==2.0.0
 jaraco.classes==3.4.0
 jaraco.context==5.3.0
 jaraco.functools==4.0.0
 jeepney==0.8.0
 Jinja2==3.1.4
-keyring==25.2.1
+keyring==25.5.0
 locket==1.0.0
 lz4==4.3.3
 markdown-it-py==3.0.0
-MarkupSafe==2.1.5
+MarkupSafe==3.0.2
 mdurl==0.1.2
-more-itertools==10.2.0
-msgpack==1.0.8
+more-itertools==10.5.0
+msgpack==1.1.0
 mypy-extensions==1.0.0
-netCDF4==1.6.5
-nodeenv==1.8.0
-numpy==1.26.4
-numpy-groupies==0.11.1
-packaging==24.0
-pandas==2.2.2
+netCDF4==1.7.1
+nodeenv==1.9.1
+numpy==2.1.3
+numpy-groupies==0.11.2
+packaging==24.1
+pandas==2.2.3
 partd==1.4.2
 pathspec==0.12.1
 pexpect==4.9.0
-pillow==10.3.0
-pip==24.0
-platformdirs==4.2.2
+pillow==11.0.0
+pip==24.3.1
+platformdirs==4.3.6
 pluggy==1.5.0
-pre_commit==3.7.1
-psutil==5.9.8
+pre_commit==4.0.1
+psutil==6.1.0
 ptyprocess==0.7.0
-pyarrow==15.0.2
-pyarrow-hotfix==0.6
+pyarrow==18.0.0
 pycparser==2.22
 Pygments==2.18.0
 PySocks==1.7.1
-pytest==8.2.1
-pytest-cov==5.0.0
+pytest==8.3.3
+pytest-cov==6.0.0
 pytest-randomly==3.15.0
 python-dateutil==2.9.0
 pytz==2024.1
-PyYAML==6.0.1
-requests==2.32.2
-rich==13.7.1
-scipy==1.13.1
+PyYAML==6.0.2
+requests==2.32.3
+Reshapr==24.1.dev0
+rich==13.9.4
+scipy==1.14.1
 SecretStorage==3.3.3
-setuptools==70.0.0
+setuptools==75.3.0
 shellingham==1.5.4
 six==1.16.0
 sniffio==1.3.1
 snowballstemmer==2.2.0
 sortedcontainers==2.4.0
-Sphinx==7.2.6
-sphinx-notfound-page==1.0.0
-sphinx-rtd-theme==2.0.0
-sphinxcontrib-applehelp==1.0.8
-sphinxcontrib-devhelp==1.0.6
-sphinxcontrib-htmlhelp==2.0.5
+Sphinx==8.1.3
+sphinx-notfound-page==1.0.4
+sphinx_rtd_theme==3.0.0
+sphinxcontrib-applehelp==2.0.0
+sphinxcontrib-devhelp==2.0.0
+sphinxcontrib-htmlhelp==2.1.0
 sphinxcontrib-jquery==4.1
 sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==1.0.7
+sphinxcontrib-qthelp==2.0.0
 sphinxcontrib-serializinghtml==1.1.10
-structlog==24.1.0
+structlog==24.4.0
 tblib==3.0.0
 toml==0.10.2
-tomli==2.0.1
-tomli_w==1.0.0
-tomlkit==0.12.5
-toolz==0.12.1
+tomli==2.0.2
+tomli_w==1.1.0
+tomlkit==0.13.2
+toolz==1.0.0
 tornado==6.4.1
-trove-classifiers==2024.5.22
-types-python-dateutil==2.9.0.20240316
-typing_extensions==4.11.0
-tzdata==2024.1
+trove-classifiers==2024.10.21.16
+types-python-dateutil==2.9.0.20241003
+typing_extensions==4.12.2
+tzdata==2024.2
 ukkonen==1.0.1
-urllib3==2.2.2
+urllib3==2.2.3
 userpath==1.7.0
-virtualenv==20.26.2
-wheel==0.43.0
-xarray==2024.5.0
-xyzservices==2024.4.0
+virtualenv==20.27.1
+wheel==0.44.0
+xarray==2024.10.0
+xyzservices==2024.9.0
 zict==3.0.0
-zipp==3.19.1
-zstandard==0.22.0
+zipp==3.20.2
+zstandard==0.23.0