diff --git a/.readthedocs.yml b/.readthedocs.yml index bee8bb7ea..832445d44 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -26,7 +26,7 @@ formats: - pdf conda: - environment: environment-rtd.yml + environment: environment-docs.yml python: install: diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 7da980c73..ea60731b8 100644 --- a/CHANGELOG.rst +++ b/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) -------------------- diff --git a/README.rst b/README.rst index c57818f07..68d6569ef 100644 --- a/README.rst +++ b/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 diff --git a/docs/RavenPy.png b/docs/RavenPy.png deleted file mode 100644 index 00e893ce9..000000000 Binary files a/docs/RavenPy.png and /dev/null differ diff --git a/docs/_static/_images/logos/ravenpy-logo-small.png b/docs/_static/_images/logos/ravenpy-logo-small.png new file mode 100644 index 000000000..9b12d87d9 Binary files /dev/null and b/docs/_static/_images/logos/ravenpy-logo-small.png differ diff --git a/docs/_static/_images/logos/ravenpy-logo.png b/docs/_static/_images/logos/ravenpy-logo.png new file mode 100644 index 000000000..13f62c6df Binary files /dev/null and b/docs/_static/_images/logos/ravenpy-logo.png differ diff --git a/docs/conf.py b/docs/conf.py index 14f5aa7d8..77cb452a0 100755 --- a/docs/conf.py +++ b/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. diff --git a/docs/notebooks/04_Emulating_hydrological_models.ipynb b/docs/notebooks/04_Emulating_hydrological_models.ipynb index fa7cc6933..0b15a5af0 100644 --- a/docs/notebooks/04_Emulating_hydrological_models.ipynb +++ b/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)" diff --git a/docs/notebooks/05_Advanced_RavenPy_configuration.ipynb b/docs/notebooks/05_Advanced_RavenPy_configuration.ipynb index b564c2448..c30949889 100644 --- a/docs/notebooks/05_Advanced_RavenPy_configuration.ipynb +++ b/docs/notebooks/05_Advanced_RavenPy_configuration.ipynb @@ -77,8 +77,7 @@ "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", @@ -86,7 +85,7 @@ "].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", diff --git a/docs/notebooks/06_Raven_calibration.ipynb b/docs/notebooks/06_Raven_calibration.ipynb index 289cf21f8..e671687ab 100644 --- a/docs/notebooks/06_Raven_calibration.ipynb +++ b/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", diff --git a/docs/user_api.rst b/docs/user_api.rst index ce5f82ab4..6224ec636 100644 --- a/docs/user_api.rst +++ b/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: diff --git a/environment-rtd.yml b/environment-docs.yml similarity index 89% rename from environment-rtd.yml rename to environment-docs.yml index 2fe24f24a..fc9f7d5f5 100644 --- a/environment-rtd.yml +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 8e4bc8fac..d5e7fa5c0 100644 --- a/pyproject.toml +++ b/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", diff --git a/src/ravenpy/config/emulators/__init__.py b/src/ravenpy/config/emulators/__init__.py index e48db8e4b..b820a6ee2 100644 --- a/src/ravenpy/config/emulators/__init__.py +++ b/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.