Add proposed temporary RavenPy logos

.readthedocs.yml

@@ -26,7 +26,7 @@ formats:
   - pdf
 
 conda:
-  environment: environment-rtd.yml
+  environment: environment-docs.yml
 
 python:
   install:

CHANGELOG.rst

@@ -8,6 +8,7 @@ v0.17.0 (unreleased)
 * Updated the cookiecutter template to the latest commit and synchronized dependencies between PyPI and Anaconda recipes. (PR #427)
 * Updated `ts_fit_graph` logic for `matplotlib` >= 3.10.0 compatibility. (PR #434)
 * Temporarily pinned `pygments` below v2.19 due to a breaking change affecting `sphinx-codeautolink`. (PR #434)
+* Adopted a new RavenPy logo for the documentation. (PR #428)
 
 v0.16.1 (2024-12-05)
 --------------------

README.rst

@@ -1,6 +1,6 @@
-=======
-RavenPy
-=======
+==============
+RavenPy |logo|
+==============
 
 +----------------------------+-----------------------------------------------------+
 | Versions                   | |pypi| |versions|                                   |
@@ -71,14 +71,18 @@ This package was created with Cookiecutter_ and the `Ouranosinc/cookiecutter-pyp
         :target: https://coveralls.io/github/CSHS-CWRA/RavenPy
         :alt: Coveralls
 
-.. |docs| image:: https://readthedocs.org/projects/RavenPy/badge/?version=latest
-        :target: https://ravenpy.readthedocs.io/en/latest/?version=latest
+.. |docs| image:: https://readthedocs.org/projects/ravenpy/badge/?version=latest
+        :target: https://ravenpy.readthedocs.io/en/latest
         :alt: Documentation Status
 
 .. |license| image:: https://img.shields.io/github/license/CSHS-CWRA/RavenPy.svg
         :target: https://github.com/CSHS-CWRA/RavenPy/blob/master/LICENSE
         :alt: License
 
+.. |logo| image:: https://raw.githubusercontent.com/CSHS-CWRA/RavenPy/main/docs/_static/_images/ravenpy-logo-small.png
+        :target: https://github.com/CSHS-CWRA/RavenPy
+        :alt: RavenPy Logo
+
 .. |ossf| image:: https://api.securityscorecards.dev/projects/github.com/CSHS-CWRA/RavenPy/badge
         :target: https://securityscorecards.dev/viewer/?uri=github.com/CSHS-CWRA/RavenPy
         :alt: OpenSSF Scorecard

docs/conf.py

@@ -213,7 +213,10 @@ def rebuild_readme():
 # 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,
+    "logo_only": True
+}
 
 # 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,
@@ -222,6 +225,8 @@ def rebuild_readme():
     os.makedirs("_static")
 html_static_path = ["_static"]
 
+html_logo = "_static/_images/logos/ravenpy-logo.png"
+
 # -- Options for HTMLHelp output ---------------------------------------
 
 # Output file base name for HTML help builder.

docs/notebooks/04_Emulating_hydrological_models.ipynb

@@ -113,9 +113,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Import required packages. We already imported the GR4JCN emulator in the first cell, but let's keep it here for\n",
-    "# completeness.\n",
-    "from ravenpy.config.emulators import GR4JCN\n",
+    "# Import required packages. We already imported the GR4JCN emulator in the first cell.\n",
+    "# from ravenpy.config.emulators import GR4JCN\n",
     "\n",
     "# Since our meteorological gauge data is all included in a single file, we need to tell the model which variables\n",
     "# we are providing. We will generate the list now and pass it later to Ravenpy as an argument to the model.\n",
@@ -235,9 +234,8 @@
    "outputs": [],
    "source": [
     "# If we want to import our own raven configuration files and forcing data, we can do so by importing them\n",
-    "# using the ravenpy.run  method. This will run the model exactly as the users will have designed it.\n",
-    "from ravenpy import OutputReader\n",
-    "from ravenpy.ravenpy import run\n",
+    "# using the ravenpy.run method. This will run the model exactly as the users will have designed it.\n",
+    "from ravenpy import OutputReader, ravenpy\n",
     "\n",
     "# This is used to specify the raven configuration files prefixes. In this case, we will retake the previously created files\n",
     "run_name = run_name\n",
@@ -247,7 +245,7 @@
     "configdir = workdir\n",
     "\n",
     "# Run the model and get the path to the outputs folder that can be used in the output reader.\n",
-    "outputs_path = run(modelname=run_name, configdir=configdir)\n",
+    "outputs_path = ravenpy.run(modelname=run_name, configdir=configdir)\n",
     "\n",
     "# Get the outputs using the Output Reader object.\n",
     "outputs = OutputReader(run_name=run_name, path=outputs_path)"

docs/notebooks/05_Advanced_RavenPy_configuration.ipynb

@@ -77,16 +77,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from ravenpy import OutputReader\n",
-    "from ravenpy.ravenpy import run\n",
+    "from ravenpy import OutputReader, ravenpy\n",
     "\n",
     "run_name = \"raven-gr4j-salmon\"  # As can be seen in the config above, this is the name of the .rvX files.\n",
     "configdir = config[\n",
     "    0\n",
     "].parent  # We can get the path to the folder containing the .rvX files this way\n",
     "\n",
     "# Run the model and get the path to outputs\n",
-    "outputs_path = run(modelname=run_name, configdir=configdir, overwrite=True)\n",
+    "outputs_path = ravenpy.run(modelname=run_name, configdir=configdir, overwrite=True)\n",
     "\n",
     "# Note. The modelname parameter can be confusing. You need to give the FILES extension name (run_name in our case),\n",
     "# not the name of the model.\n",
@@ -107,7 +106,7 @@
     "# compared to the one above, you should change the run_name value to this new name. It's important though that you keep the end\n",
     "# of the filename the same\n",
     "\n",
-    "# Show the list of files that were retrived by the OutputReader\n",
+    "# Show the list of files that were retrieved by the OutputReader\n",
     "outputs.files"
    ]
   },
@@ -213,7 +212,7 @@
     "\n",
     "from ravenpy import Emulator\n",
     "from ravenpy.config import commands as rc\n",
-    "from ravenpy.config.emulators import GR4JCN\n",
+    "from ravenpy.config import emulators\n",
     "\n",
     "# Observed weather data for the Salmon river. We extracted this using Tutorial Notebook 03 and the\n",
     "# salmon_river.geojson file as the contour.\n",
@@ -269,7 +268,7 @@
    "outputs": [],
    "source": [
     "# Run the model (See Notebook 04 for more details on implementation)\n",
-    "m = GR4JCN(\n",
+    "m = emulators.GR4JCN(\n",
     "    params=parameters,\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",
@@ -324,7 +323,7 @@
    "outputs": [],
    "source": [
     "# Run the model (See Notebook 04 for more details on implementation)\n",
-    "m = GR4JCN(\n",
+    "m = emulators.GR4JCN(\n",
     "    params=parameters,\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",
@@ -434,7 +433,7 @@
    "outputs": [],
    "source": [
     "# Run the model (See Notebook 04 for more details on implementation)\n",
-    "m = GR4JCN(\n",
+    "m = emulators.GR4JCN(\n",
     "    params=parameters,\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",
@@ -503,7 +502,7 @@
    "outputs": [],
    "source": [
     "# Run the model (See Notebook 04 for more details on implementation)\n",
-    "m = GR4JCN(\n",
+    "m = emulators.GR4JCN(\n",
     "    params=parameters,\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",

docs/notebooks/06_Raven_calibration.ipynb

@@ -32,7 +32,7 @@
     "import spotpy\n",
     "\n",
     "from ravenpy.config import commands as rc\n",
-    "from ravenpy.config.emulators import GR4JCN\n",
+    "from ravenpy.config import emulators\n",
     "from ravenpy.utilities.calibration import SpotSetup"
    ]
   },
@@ -109,7 +109,7 @@
     "\n",
     "\n",
     "# We need to create the desired model with its parameters the same way as in the Notebook 04_Emulating_hydrological_models.\n",
-    "model_config = GR4JCN(\n",
+    "model_config = emulators.GR4JCN(\n",
     "    ObservationData=[rc.ObservationData.from_nc(nc_file, alt_names=\"qobs\")],\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",

docs/user_api.rst

@@ -37,6 +37,7 @@ Utilities
 
 Geospatial
 ----------
+
 .. automodule::  ravenpy.utilities.io
    :members:
 
@@ -48,6 +49,7 @@ Geospatial
 
 Graphics
 --------
+
 .. automodule::  ravenpy.utilities.graphs
    :members:
 

environment-rtd.yml → environment-docs.yml

@@ -1,4 +1,4 @@
-name: ravenpy-rtd
+name: ravenpy-docs
 channels:
 - conda-forge
 - defaults
@@ -31,7 +31,7 @@ dependencies:
   - sphinx >=7.0.0
   - sphinx-autoapi
   - sphinx-click
-  - sphinx-codeautolink
+  - sphinx-codeautolink >=0.15.2,!=0.16.0 # FIXME: temporary fix for sphinx-codeautolink
   - sphinx-copybutton
   - sphinx-rtd-theme >=1.0
   - sphinxcontrib-svg2pdfconverter

pyproject.toml

@@ -120,7 +120,7 @@ docs = [
   "s3fs",
   "sphinx >=7.0.0",
   "sphinx-click",
-  "sphinx-codeautolink",
+  "sphinx-codeautolink >=0.15.2,!=0.16.0", # FIXME: temporary fix for sphinx-codeautolink
   "sphinx-copybutton",
   "sphinx-rtd-theme >=1.0",
   "sphinxcontrib-svg2pdfconverter >=1.2.3",

src/ravenpy/config/emulators/__init__.py

@@ -8,6 +8,19 @@
 from ravenpy.config.emulators.routing import BasicRoute
 from ravenpy.config.emulators.sacsma import SACSMA
 
+__all__ = [
+    "GR4JCN",
+    "HBVEC",
+    "HMETS",
+    "HYPR",
+    "SACSMA",
+    "BasicRoute",
+    "Blended",
+    "CanadianShield",
+    "Mohyse",
+    "get_model",
+]
+
 
 def get_model(name):
     """Return the corresponding Raven emulator configuration class.