Address several documentation warnings

CHANGELOG.rst

@@ -14,6 +14,12 @@ What's New
     # cut border when saving (for maps)
     mpl.rcParams["savefig.bbox"] = "tight"
 
+climpred v2.5.0 (unreleased)
+============================
+
+Internals/Minor Fixes
+---------------------
+- Fixed some issues with the documentation build to address rendering errors and reduce the number of warnings on ReadTheDocs. (pr:`843`) `Trevor James Smith`_
 
 climpred v2.4.0 (2023-11-09)
 ============================
@@ -658,7 +664,7 @@ Internals/Minor Fixes
   (:issue:`402`, :pr:`403`) `Aaron Spring`_.
 - ``dim`` is expected to be a list of strings in
   :py:func:`~climpred.prediction.compute_perfect_model` and
-  :py:func:`~climpred.prediction.compute_hindcast`.
+  `~climpred.prediction.compute_hindcast`.
   (:issue:`282`, :pr:`407`) `Aaron Spring`_.
 - Update ``cartopy`` requirement to 0.0.18 or greater to release lock on
   ``matplotlib`` version. Update ``xskillscore`` requirement to 0.0.18 to
@@ -721,8 +727,8 @@ The major change for this release is a dramatic speedup in bootstrapping functio
 
 - Bootstrapping uninitialized skill in the perfect model framework is now sped up
   significantly for annual lead resolution. (:pr:`332`) `Aaron Spring`_.
-- General speedup in :py:func:`~climpred.bootstrap.bootstrap_hindcast` and
-  :py:func:`~climpred.bootstrap.bootstrap_perfect_model`: (:pr:`285`) `Aaron Spring`_.
+- General speedup in ``~climpred.bootstrap.bootstrap_hindcast`` and
+  ``~climpred.bootstrap.bootstrap_perfect_model``: (:pr:`285`) `Aaron Spring`_.
 
     * Properly implemented handling for lazy results when inputs are chunked.
 
@@ -747,7 +753,7 @@ Internals/Minor Fixes
   (:pr:`330`) `Aaron Spring`_.
 - Remove ``member`` coords for ``m2c`` comparison for probabilistic metrics.
   (:pr:`330`) `Aaron Spring`_.
-- Refactored :py:func:`~climpred.prediction.compute_hindcast` and
+- Refactored ``~climpred.prediction.compute_hindcast`` and
   :py:func:`~climpred.prediction.compute_perfect_model`. (:pr:`330`) `Aaron Spring`_.
 - Changed lead0 coordinate modifications to be compliant with ``xarray=0.15.1`` in
   :py:func:`~climpred.reference.compute_persistence`. (:pr:`348`) `Aaron Spring`_.
@@ -763,8 +769,8 @@ Internals/Minor Fixes
 - Require ``cftime v1.1.2``, which modifies their object handling to create 200-400x
   speedups in some basic operations. (:pr:`356`) `Riley X. Brady`_.
 - Resample first and then calculate skill in
-  :py:func:`~climpred.bootstrap.bootstrap_perfect_model` and
-  :py:func:`~climpred.bootstrap.bootstrap_hindcast` (:pr:`355`) `Aaron Spring`_.
+  `~climpred.bootstrap.bootstrap_perfect_model` and
+  `~climpred.bootstrap.bootstrap_hindcast` (:pr:`355`) `Aaron Spring`_.
 
 Documentation
 -------------

HOWTORELEASE.rst

@@ -18,14 +18,13 @@ changes, a minor version adds functionality, and a patch covers bug fixes.
     $ git tag -a v1.0.0 -m "Version 1.0.0"
     $ git push upstream main --tags
 
-#. We use Github Actions to automate the new release being published to TestPyPI (staging) and PyPI (production).
-   When a tag is pushed to the repository, the following happens:
+#. We use Github Actions to automate the new release being published to TestPyPI (staging) and PyPI (production). When a tag is pushed to the repository, the following happens:
     - A new release is drafted on Github
     - The library is built and a workflow is staged for publishing to TestPyPI
         - A maintainer must manually approve the workflow to publish to TestPyPI
     - If everything clears, maintainers can then finalize the release on GitHub, triggering an upload to PyPI
 
-   If you wish to circumvent the GitHub Actions for whatever reason, you can manually do it by running the following::
+    If you wish to circumvent the GitHub Actions for whatever reason, you can manually do it by running the following::
 
     $ git clean -xfd  # remove any files not checked into git
     $ python -m build  # build package

ci/requirements/docs.yml

@@ -16,7 +16,7 @@ dependencies:
   - myst-nb
   - nbstripout
   - sphinx
-  - sphinx-book-theme
+  - sphinx-book-theme >=0.3.3
   - sphinx-copybutton
   - sphinxcontrib-bibtex
   - sphinxcontrib-napoleon
@@ -26,8 +26,8 @@ dependencies:
   - bias_correction
   - esmpy=*=mpi*  # Ensures MPI works with version of esmpy.
   - esmtools
-  - nc-time-axis>=1.4.0
-  - numba>=0.52
+  - nc-time-axis >=1.4.0
+  - numba >=0.52
   - xclim
   - xesmf
   - xrft

docs/source/alignment.ipynb

@@ -11,7 +11,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Verification Alignment\n",
+    "# Verification Alignment\n",
     "\n",
     "A forecast is verified by comparing a set of initializations at a given lead to\n",
     "observations over some window of time. However, there are a few ways to decide *which*\n",

docs/source/api.rst

@@ -220,9 +220,9 @@ Bootstrap
 
     bootstrap_uninit_pm_ensemble_from_control_cftime
     bootstrap_uninitialized_ensemble
-    resample_skill_exclude_resample_dim_from_dim,
-    resample_skill_loop,
-    resample_skill_resample_before,
+    resample_skill_exclude_resample_dim_from_dim
+    resample_skill_loop
+    resample_skill_resample_before
     dpp_threshold
     varweighted_mean_period_threshold
 

docs/source/api/climpred.bootstrap.bootstrap_compute.rst

@@ -2,5 +2,3 @@ climpred.bootstrap.bootstrap\_compute
 =====================================
 
 .. currentmodule:: climpred.bootstrap
-
-.. autofunction:: bootstrap_compute

docs/source/api/climpred.bootstrap.bootstrap_hindcast.rst

@@ -2,5 +2,3 @@ climpred.bootstrap.bootstrap\_hindcast
 ======================================
 
 .. currentmodule:: climpred.bootstrap
-
-.. autofunction:: bootstrap_hindcast

docs/source/api/climpred.bootstrap.bootstrap_perfect_model.rst

@@ -2,5 +2,3 @@ climpred.bootstrap.bootstrap\_perfect\_model
 ============================================
 
 .. currentmodule:: climpred.bootstrap
-
-.. autofunction:: bootstrap_perfect_model

docs/source/api/climpred.prediction.compute_hindcast.rst

@@ -2,5 +2,3 @@ climpred.prediction.compute\_hindcast
 =====================================
 
 .. currentmodule:: climpred.prediction
-
-.. autofunction:: compute_hindcast

docs/source/conf.py

@@ -125,7 +125,6 @@
 html_theme_options = {
     "repository_url": "https://github.com/pangeo-data/climpred",
     "use_edit_page_button": True,
-    "navbar_end": "search-field.html",
     "repository_branch": "main",
     "path_to_docs": "docs/source",
     "use_edit_page_button": True,
@@ -151,12 +150,12 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    "xarray": ("https://xarray.pydata.org/en/stable/", None),
+    "esmtools": ("https://esmtools.readthedocs.io/en/latest", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
-    "numpy": ("https://docs.scipy.org/doc/numpy/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable", None),
+    "xclim": ("https://xclim.readthedocs.io/en/latest", None),
     "xskillscore": ("https://xskillscore.readthedocs.io/en/stable", None),
-    "xclim": ("https://xclim.readthedocs.io/en/latest/", None),
-    "esmtools": ("https://esmtools.readthedocs.io/en/latest/", None),
 }
 
 # Should only be uncommented when testing page development while notebooks
@@ -165,8 +164,7 @@
 nbsphinx_allow_errors = True
 nbsphinx_timeout = 600
 nbsphinx_execute = "auto"  # "never" "always"
-jupyter_execute_notebooks = "auto"
-
+nb_execution_mode = "auto"
 
 # Napoleon configurations
 napoleon_google_docstring = True

setup.py

@@ -54,7 +54,7 @@
     "myst_nb",
     "sphinx",
     "sphinx-copybutton",
-    "sphinx_book_theme",
+    "sphinx-book-theme>=0.3.3",
     "sphinxcontrib-bibtex",
     "sphinxcontrib-napoleon",
 ]