move logos to _static, replace sphinx-rtd-theme with furo, fix README…

… formatting, add option to not run notebooks

README.rst

@@ -23,8 +23,8 @@ Features
 --------
 
 * The `xsdba` submodule provides a collection of bias-adjustment methods meant to correct for systematic biases found in climate model simulations relative to observations.
-Almost all adjustment algorithms conform to the `train` - `adjust` scheme, meaning that adjustment factors are first estimated on training data sets, then applied in a distinct step to the data to be adjusted.
-Given a reference time series (`ref`), historical simulations (`hist`) and simulations to be adjusted (`sim`), any bias-adjustment method would be applied by first estimating the adjustment factors between the historical simulation and the observation series, and then applying these factors to `sim``, which could be a future simulation:
+  Almost all adjustment algorithms conform to the `train` - `adjust` scheme, meaning that adjustment factors are first estimated on training data sets, then applied in a distinct step to the data to be adjusted.
+  Given a reference time series (`ref`), historical simulations (`hist`) and simulations to be adjusted (`sim`), any bias-adjustment method would be applied by first estimating the adjustment factors between the historical simulation and the observation series, and then applying these factors to `sim``, which could be a future simulation:
 
 * Time grouping (months, day of year, season) can be done within bias adjustment methods.
 
@@ -61,7 +61,6 @@ This package was created with Cookiecutter_ and the `Ouranosinc/cookiecutter-pyp
         :target: https://github.com/psf/black
         :alt: Python Black
 
-
 .. |build| image:: https://github.com/Ouranosinc/xsdba/actions/workflows/main.yml/badge.svg
         :target: https://github.com/Ouranosinc/xsdba/actions
         :alt: Build Status

docs/conf.py

@@ -19,6 +19,7 @@
 #
 import os
 import sys
+import warnings
 
 sys.path.insert(0, os.path.abspath('..'))
 
@@ -54,7 +55,6 @@
     'sphinx_codeautolink',
     'sphinx_copybutton',
     "nbsphinx",
-
 ]
 
 # suppress "duplicate citation for key" warnings
@@ -101,6 +101,19 @@ class XCStyle(AlphaStyle):
     "user": ("https://github.com/%s", "@%s"),
 }
 
+skip_notebooks = os.getenv("SKIP_NOTEBOOKS")
+if skip_notebooks or os.getenv("READTHEDOCS_VERSION_TYPE") in [
+    "branch",
+    "external",
+]:
+    if skip_notebooks:
+        warnings.warn("Not executing notebooks.")
+    nbsphinx_execute = "never"
+elif os.getenv("READTHEDOCS_VERSION_NAME") in ["latest", "stable"]:
+    nbsphinx_execute = "always"
+else:
+    nbsphinx_execute = "auto"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -154,20 +167,20 @@ class XCStyle(AlphaStyle):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"
 
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the
 # documentation.
 #
-html_theme_options = {"style_external_links": True}
+# html_theme_options = {"style_external_links": True}
 
 
 # Theme options are theme-specific and customize the look and feel of a theme further.
 # For a list of options available for each theme, see the documentation.
 html_theme_options = {
-    "light_logo": "xsdba-logo-light.png",
-    "dark_logo": "xsdba-logo-dark.png",
+    "light_logo": "logos/xsdba-logo-light.png",
+    "dark_logo": "logos/xsdba-logo-dark.png",
     "footer_icons": [
         {
             "name": "GitHub",
@@ -245,14 +258,16 @@ class XCStyle(AlphaStyle):
     ]
 }
 
-
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = "logos/xsdba-logo-light.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 if not os.path.exists("_static"):
     os.makedirs("_static")
-html_static_path = ["logos", "_static"]
+html_static_path = ["_static"]
 
 
 # -- Options for HTMLHelp output ---------------------------------------
@@ -291,11 +306,6 @@ class XCStyle(AlphaStyle):
 
 latex_engine = "pdflatex"
 latex_logo = "logos/xsdba-logo-light.png"
-html_logo = "xsdba-logo-light.png"
-html_theme_options = {
-    'logo_only': True,
-    'display_version': False,
-}
 
 # -- Options for manual page output ------------------------------------
 

environment-docs.yml

@@ -5,8 +5,8 @@ channels:
 dependencies:
   - python >=3.12,<3.13
   - sphinx >=7.0.0
+  - furo >=2023.9.10
   - pandoc
-  - sphinx-rtd-theme >=1.0
   - sphinx-autoapi
   - sphinx-codeautolink
   - sphinx-copybutton

pyproject.toml

@@ -79,12 +79,12 @@ dev = [
 ]
 docs = [
   # Documentation and examples
+  "furo >=2023.9.10",
   "pooch >=1.8.0",
   "sphinx >=7.0.0",
   "sphinx-codeautolink",
   "sphinx-copybutton",
   "sphinx-intl",
-  "sphinx-rtd-theme >=1.0",
   "nbsphinx",
   "ipython",
   "ipykernel",