From 689ee4dee69c50e6d8826410cd6573c2546d8330 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 09:33:22 -0500
Subject: [PATCH 01/27] Add workflow to render documentation

---
 .github/workflows/render_example_gallery.yml | 85 ++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 .github/workflows/render_example_gallery.yml

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
new file mode 100644
index 000000000..670299858
--- /dev/null
+++ b/.github/workflows/render_example_gallery.yml
@@ -0,0 +1,85 @@
+# Execute the examples, in the form of pythons scripts, and generate the example
+# gallery using sphinx-gallery. Then, trigger ReadTheDocs.concurrency: concurrency:
+
+# Workflow inspired by the https://github.com/dfm/rtds-action project and the
+# following wradlib-notebooks CI task:
+# https://github.com/wradlib/wradlib-notebooks/blob/main/.github/workflows/main.yml
+name: Render the example gallery
+
+on:
+  # Triggers the workflow on push or pull request events to the master branch
+  push:
+    branches: [ master, rtd_using_gh_artifacts ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  render_example_gallery:
+    name: Render the example gallery
+    runs-on: "ubuntu-latest"
+
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    outputs:
+      rtd_branch: ${{steps.set_rendered_branch.outputs.render_branch}}
+      gallery_branch: ${{steps.set_rendered_branch.outputs.render_branch}}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Install mamba and create environment
+        uses: mamba-org/provision-with-micromamba@main
+        with:
+          environment-file: ci/ci_test_env.yml
+          extra-specs: python=3.8
+          environment-name: doc_builder
+
+      - name: Install pygrib
+        run: mamba install --quiet pygrib
+
+      - name: Install sphinx dependencies using pip
+        run: |
+          pip install -r docs/requirements.txt
+
+      - name: Install pysteps
+        working-directory: ${{ env.PYSTEPS_MAIN_REPO }}
+        run: |
+          pip install .          
+
+      - name: Install pysteps-data
+        run: |
+          python ci/fetch_pysteps_data.py $HOME/pysteps_data
+          python -c "import pysteps; print(pysteps.config_fname())"  
+
+      - name: Build example gallery
+        working-directory: ./docs
+        run: |
+          make html       
+
+      - uses: actions/upload-artifact@v2
+        with:
+          name: auto_examples-for-${{ github.sha }}
+          path: doc/source/auto_examples
+
+#  trigger_rtd:
+#    # Task adapted from the wradlib project
+#    # https://github.com/wradlib/wradlib-notebooks/blob/main/.github/workflows/render_notebooks.yml
+#    needs: [ run_notebooks ]
+#    name: Trigger readthedocs
+#    runs-on: ubuntu-latest
+#    defaults:
+#      run:
+#        shell: bash -l {0}
+#    env:
+#      RTD_TOKEN: ${{ secrets.PYSTEPS_BOT_RTD_TOKEN }}
+#      RTD_URL: ${{ secrets.RTD_URL }}
+#      RTD_BRANCH: ${{steps.parse_commit_msg.outputs.rtd_branch}}
+#    steps:
+#      - name: Trigger readthedocs for the corresponding branch (latest or tag)
+#        run: |
+#          if [[ ! -z "${RTD_BRANCH}" ]]; then
+#            curl -X POST -d "branches=${RTD_BRANCH}" -d "token=${RTD_TOKEN}" "${RTD_URL}"
+#          fi

From 523153f8f0721f00a7fcff24b4c9f87c0dcc3711 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 09:40:34 -0500
Subject: [PATCH 02/27] Fix requirements.txt path

---
 .github/workflows/render_example_gallery.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index 670299858..f6c482bfd 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -42,7 +42,7 @@ jobs:
 
       - name: Install sphinx dependencies using pip
         run: |
-          pip install -r docs/requirements.txt
+          pip install -r doc/requirements.txt
 
       - name: Install pysteps
         working-directory: ${{ env.PYSTEPS_MAIN_REPO }}

From 2a15d4652b72d889db67aa5576124069128b4382 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 09:46:45 -0500
Subject: [PATCH 03/27] Add PYSTEPS_DATA_PATH

---
 .github/workflows/render_example_gallery.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index f6c482bfd..669bfaf7b 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -50,6 +50,8 @@ jobs:
           pip install .          
 
       - name: Install pysteps-data
+        env:
+          PYSTEPS_DATA_PATH: ${{github.workspace}}/pysteps_data
         run: |
           python ci/fetch_pysteps_data.py $HOME/pysteps_data
           python -c "import pysteps; print(pysteps.config_fname())"  

From b125626ab312622b2e216257d5c1fedf15d259ba Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 09:55:56 -0500
Subject: [PATCH 04/27] Fix working dir for pysteps installation

---
 .github/workflows/render_example_gallery.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index 669bfaf7b..679c21ffd 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -45,7 +45,7 @@ jobs:
           pip install -r doc/requirements.txt
 
       - name: Install pysteps
-        working-directory: ${{ env.PYSTEPS_MAIN_REPO }}
+        working-directory: ${{github.workspace}}
         run: |
           pip install .          
 

From 2976accd91ece2edba7680a09f9b1010aec70aa1 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 10:00:32 -0500
Subject: [PATCH 05/27] Add option to silent the dataset download progress

---
 ci/fetch_pysteps_data.py |  2 +-
 pysteps/datasets.py      | 11 +++++++++--
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/ci/fetch_pysteps_data.py b/ci/fetch_pysteps_data.py
index 7172447da..d9db279ed 100644
--- a/ci/fetch_pysteps_data.py
+++ b/ci/fetch_pysteps_data.py
@@ -15,7 +15,7 @@
 
 tox_test_data_dir = os.environ["PYSTEPS_DATA_PATH"]
 
-download_pysteps_data(tox_test_data_dir, force=True)
+download_pysteps_data(tox_test_data_dir, force=True, show_progress=False)
 
 create_default_pystepsrc(
     tox_test_data_dir, config_dir=tox_test_data_dir, file_name="pystepsrc"
diff --git a/pysteps/datasets.py b/pysteps/datasets.py
index c75bdf02c..b1dfa4d8d 100644
--- a/pysteps/datasets.py
+++ b/pysteps/datasets.py
@@ -285,7 +285,7 @@ def delay(_counter):
             print(err)
 
 
-def download_pysteps_data(dir_path, force=True):
+def download_pysteps_data(dir_path, force=True, show_progress=True):
     """
     Download pysteps data from github.
 
@@ -298,6 +298,8 @@ def download_pysteps_data(dir_path, force=True):
         exception if raised.
         If force=True, the data will we downloaded in the destination directory and may
         override existing files.
+    show_progess: bool
+        If true, show the download progress.
     """
 
     # Check if directory exists but is not empty
@@ -317,9 +319,14 @@ def download_pysteps_data(dir_path, force=True):
     # the content is dynamically generated and we can't know the length a priori easily.
     pbar = ShowProgress()
     print("Downloading pysteps-data from github.")
+
+    if show_progress:
+        reporthook = pbar
+    else:
+        reporthook = None
     tmp_file_name, _ = request.urlretrieve(
         "https://github.com/pySTEPS/pysteps-data/archive/master.zip",
-        reporthook=pbar,
+        reporthook=reporthook,
     )
     pbar.end(message="Download complete\n")
 

From b7163d6c3f201723e7be5bc00650479591145cbd Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 10:03:28 -0500
Subject: [PATCH 06/27] Update working dir for download data step

---
 .github/workflows/render_example_gallery.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index 679c21ffd..f9aeccb13 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -52,8 +52,9 @@ jobs:
       - name: Install pysteps-data
         env:
           PYSTEPS_DATA_PATH: ${{github.workspace}}/pysteps_data
+        working-directory: ${{github.workspace}}/ci
         run: |
-          python ci/fetch_pysteps_data.py $HOME/pysteps_data
+          python fetch_pysteps_data.py
           python -c "import pysteps; print(pysteps.config_fname())"  
 
       - name: Build example gallery

From efcb30603ef714c5c9ecee2185065644f03f45bd Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 10:07:59 -0500
Subject: [PATCH 07/27] Replace ./docs -> ./doc

---
 .github/workflows/render_example_gallery.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index f9aeccb13..3a61d3e34 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -58,7 +58,7 @@ jobs:
           python -c "import pysteps; print(pysteps.config_fname())"  
 
       - name: Build example gallery
-        working-directory: ./docs
+        working-directory: ./doc
         run: |
           make html       
 

From 3cf90adfd01580b31aad407d134820978fa81f5c Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 10:14:27 -0500
Subject: [PATCH 08/27] Install pysteps as development to build extensions in
 place.

---
 .github/workflows/render_example_gallery.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index 3a61d3e34..79bfc2e68 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -47,7 +47,7 @@ jobs:
       - name: Install pysteps
         working-directory: ${{github.workspace}}
         run: |
-          pip install .          
+          pip install -e .          
 
       - name: Install pysteps-data
         env:

From f325d90fa619f21ce91fd801ab1388e8380fa9e1 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 10:21:18 -0500
Subject: [PATCH 09/27] Set PYSTEPSRC

---
 .github/workflows/render_example_gallery.yml | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index 79bfc2e68..09bf80ef4 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -1,5 +1,5 @@
-# Execute the examples, in the form of pythons scripts, and generate the example
-# gallery using sphinx-gallery. Then, trigger ReadTheDocs.concurrency: concurrency:
+# Execute the examples, in the form of python scripts, and render the examples
+# using sphinx-gallery. Then, trigger ReadTheDocs.
 
 # Workflow inspired by the https://github.com/dfm/rtds-action project and the
 # following wradlib-notebooks CI task:
@@ -59,6 +59,8 @@ jobs:
 
       - name: Build example gallery
         working-directory: ./doc
+        env:
+          PYSTEPSRC: ${{github.workspace}}/pysteps_data/pystepsrc
         run: |
           make html       
 

From 66b8eeebc296e7b44155a705a4272a86ceedab12 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 11:10:25 -0500
Subject: [PATCH 10/27] Tar artifact files to preserve files names and
 properties

---
 .github/workflows/render_example_gallery.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index 09bf80ef4..e9f4f6fee 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -64,6 +64,11 @@ jobs:
         run: |
           make html       
 
+      - name: Tar auto_examples files
+        # Needed to maintain permissions and case-sensitive files
+        # https://github.com/actions/upload-artifact#maintaining-file-permissions-and-case-sensitive-files
+        run: tar -cvf auto_examples.tar doc/source/auto_examples
+
       - uses: actions/upload-artifact@v2
         with:
           name: auto_examples-for-${{ github.sha }}

From 9a7c0dfcb014fe36cd7352f731e87a9309d13afb Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 11:11:53 -0500
Subject: [PATCH 11/27] Upload auto_examples.tar artifact

---
 .github/workflows/render_example_gallery.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index e9f4f6fee..8492322b2 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -72,7 +72,7 @@ jobs:
       - uses: actions/upload-artifact@v2
         with:
           name: auto_examples-for-${{ github.sha }}
-          path: doc/source/auto_examples
+          path: auto_examples.tar
 
 #  trigger_rtd:
 #    # Task adapted from the wradlib project

From 150fe51f52c53235b276ee0f3bace89c65a9fe8e Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 11:32:11 -0500
Subject: [PATCH 12/27] Do not tar intermediate dirs

---
 .github/workflows/render_example_gallery.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index 8492322b2..9eb68698c 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -67,7 +67,7 @@ jobs:
       - name: Tar auto_examples files
         # Needed to maintain permissions and case-sensitive files
         # https://github.com/actions/upload-artifact#maintaining-file-permissions-and-case-sensitive-files
-        run: tar -cvf auto_examples.tar doc/source/auto_examples
+        run: tar -cvf auto_examples.tar -C doc/source/auto_examples .
 
       - uses: actions/upload-artifact@v2
         with:

From 353000dbc48ea3f85b97cfc180bcdf6e0ad04d9b Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 12:42:54 -0500
Subject: [PATCH 13/27] Fix title underline

---
 examples/thunderstorm_detection_and_tracking.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/examples/thunderstorm_detection_and_tracking.py b/examples/thunderstorm_detection_and_tracking.py
index aa27ef75f..c0e793fed 100644
--- a/examples/thunderstorm_detection_and_tracking.py
+++ b/examples/thunderstorm_detection_and_tracking.py
@@ -1,8 +1,7 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
+#!/bin/env python
 """
 Thunderstorm Detection and Tracking - T-DaTing
-============================================
+==============================================
 
 This example shows how to use the thunderstorm DaTing module. The example is based on
 MeteoSwiss radar data and uses the Cartesian composite of maximum reflectivity on a

From 38c770b900efe394fb4066183fb6adb6d3ec1d79 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 12:46:44 -0500
Subject: [PATCH 14/27] Use artifact with rendered gallery in RTD

---
 doc/source/conf.py      | 245 +++++-----------------------------------
 doc/source/doc_utils.py | 130 +++++++++++++++++++++
 2 files changed, 161 insertions(+), 214 deletions(-)
 create mode 100644 doc/source/doc_utils.py

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 5ed946c71..2239cabcf 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -1,143 +1,49 @@
-# -*- coding: utf-8 -*-
-
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
+# Pysteps-docs sphinx configuration
 import os
-import subprocess
 import sys
 from datetime import datetime
+from pathlib import Path
 
-import json
-from jsmin import jsmin
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-if "READTHEDOCS" not in os.environ:
-    sys.path.insert(1, os.path.abspath("../../"))
-
-# -- General configuration ------------------------------------------------
+sys.path.insert(0, str(Path(__file__).parent))
+import doc_utils
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-needs_sphinx = "1.6"
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.coverage",
     "sphinx.ext.mathjax",
-    "sphinx.ext.napoleon",
+    "numpydoc",
     "sphinxcontrib.bibtex",
     "sphinx_gallery.gen_gallery",
 ]
 
 bibtex_bibfiles = ["references.bib"]
-
-# numpydoc_show_class_members = False
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
 source_suffix = ".rst"
-
-# The master toctree document.
 master_doc = "index"
-
-# General information about the project.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
+todo_include_todos = False
 project = "pysteps"
 copyright = f"2018-{datetime.now():%Y}, pysteps developers"
-author = "pysteps developers"
-
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-def get_version():
-    """Returns project version as string from 'git describe' command."""
-
-    from subprocess import check_output
-
-    _version = check_output(["git", "describe", "--tags", "--always"])
-
-    if _version:
-        return _version.decode("utf-8")
-    else:
-        return "X.Y"
-
-
-# The short X.Y version.
-version = get_version().lstrip("v").rstrip().split("-")[0]
-
-# The full version, including alpha/beta/rc tags.
-release = version
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
-
-# -- Read the Docs build --------------------------------------------------
-
-
-def set_root():
-    fn = os.path.abspath(os.path.join("..", "..", "pysteps", "pystepsrc"))
-    with open(fn, "r") as f:
-        rcparams = json.loads(jsmin(f.read()))
+author = "PySteps developers"
 
-    for key, value in rcparams["data_sources"].items():
-        new_path = os.path.join("..", "..", "pysteps-data", value["root_path"])
-        new_path = os.path.abspath(new_path)
-
-        value["root_path"] = new_path
-
-    fn = os.path.abspath(os.path.join("..", "..", "pystepsrc.rtd"))
-    with open(fn, "w") as f:
-        json.dump(rcparams, f, indent=4)
+release = doc_utils.current_release()
+version = release.lstrip("v").rstrip().split("-")[0]  # The short X.Y version.
 
+sphinx_gallery_conf = {
+    "examples_dirs": "../../examples",
+    "gallery_dirs": "user_guide/auto_examples",
+    "filename_pattern": r"/*\.py",
+    "plot_gallery": True,
+}
 
 if "READTHEDOCS" in os.environ:
-    repourl = "https://github.com/pySTEPS/pysteps-data.git"
-    dir = os.path.join(os.getcwd(), "..", "..", "pysteps-data")
-    dir = os.path.abspath(dir)
-    subprocess.check_call(["rm", "-rf", dir])
-    subprocess.check_call(["git", "clone", repourl, dir])
-    set_root()
-    pystepsrc = os.path.abspath(os.path.join("..", "..", "pystepsrc.rtd"))
-    os.environ["PYSTEPSRC"] = pystepsrc
+    # In RTD, we use the rendered examples
+    sphinx_gallery_conf["plot_gallery"] = False
 
 # -- Options for HTML output ----------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-# html_theme = 'alabaster'
-# html_theme = 'classic'
 html_theme = "sphinx_book_theme"
 html_title = ""
-
 html_context = {
     "github_user": "pySTEPS",
     "github_repo": "pysteps",
@@ -145,10 +51,6 @@ def set_root():
     "doc_path": "doc",
 }
 
-# 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 = {
     "repository_url": "https://github.com/pySTEPS/pysteps",
     "repository_branch": "master",
@@ -158,108 +60,23 @@ def set_root():
     "use_issues_button": True,
 }
 
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
 html_logo = "../_static/pysteps_logo.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".
 html_static_path = ["../_static"]
 html_css_files = ["../_static/pysteps.css"]
-
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# This is required for the alabaster theme
-# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-# html_sidebars = {
-#     "**": [
-#         "relations.html",  # needs 'show_related': True theme option to display
-#         "searchbox.html",
-#     ]
-# }
-
 html_domain_indices = True
-
 autosummary_generate = True
-
-# -- Options for HTMLHelp output ------------------------------------------
-
-# Output file base name for HTML help builder.
 htmlhelp_basename = "pystepsdoc"
 
-# -- Options for LaTeX output ---------------------------------------------
-
-# This hack is taken from numpy (https://github.com/numpy/numpy/blob/master/doc/source/conf.py).
-latex_preamble = r"""
-    \usepackage{amsmath}
-    \DeclareUnicodeCharacter{00A0}{\nobreakspace}
-    
-    % In the parameters section, place a newline after the Parameters
-    % header
-    \usepackage{expdlist}
-    \let\latexdescription=\description
-    \def\description{\latexdescription{}{} \breaklabel}
-    
-    % Make Examples/etc section headers smaller and more compact
-    \makeatletter
-    \titleformat{\paragraph}{\normalsize\py@HeaderFamily}%
-                {\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor}
-    \titlespacing*{\paragraph}{0pt}{1ex}{0pt}
-    \makeatother
-    
-    % Fix footer/header
-    \renewcommand{\chaptermark}[1]{\markboth{\MakeUppercase{\thechapter.\ #1}}{}}
-    \renewcommand{\sectionmark}[1]{\markright{\MakeUppercase{\thesection.\ #1}}}
-"""
-
-latex_elements = {
-    "papersize": "a4paper",
-    "pointsize": "10pt",
-    "preamble": latex_preamble
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-latex_domain_indices = False
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, "pysteps.tex", "pysteps reference", author, "manual"),
-]
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "pysteps", "pysteps reference", [author], 1)]
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        master_doc,
-        "pysteps",
-        "pysteps reference",
-        author,
-        "pysteps",
-        "One line description of project.",
-        "Miscellaneous",
-    ),
-]
-
-# -- Options for Sphinx-Gallery -------------------------------------------
-
-# The configuration dictionary for Sphinx-Gallery
-
-sphinx_gallery_conf = {
-    "examples_dirs": "../../examples",  # path to your example scripts
-    "gallery_dirs": "auto_examples",  # path where to save gallery generated examples
-    "filename_pattern": r"/*\.py",  # Include all the files in the examples dir
-}
+# -- Download artifacts with rendered examples------------------------------------------
+my_artifact_downloader = doc_utils.ArtifactDownloader(
+    "pySTEPS/pysteps", prefix="auto_examples-for-"
+)
+
+DOC_ROOT_DIR = Path(__file__).parent / "../"
+token = os.environ.get("RTD_GITHUB_TOKEN")  # never print this!
+my_artifact_downloader.download_artifact(
+    token,
+    DOC_ROOT_DIR / "source/auto_examples",
+    retry=3,
+    tar_filename="auto_examples.tar",
+)
diff --git a/doc/source/doc_utils.py b/doc/source/doc_utils.py
new file mode 100644
index 000000000..c3dbcef37
--- /dev/null
+++ b/doc/source/doc_utils.py
@@ -0,0 +1,130 @@
+# Adapted from the rtds_action sphinx extension.
+# https://github.com/dfm/rtds-action/blob/main/src/rtds_action/rtds_action.py
+# MIT License
+# Copyright (c) 2021 Pysteps developers
+# Copyright (c) 2020 Dan Foreman-Mackey
+
+import os
+import subprocess
+import tarfile
+import tempfile
+from io import BytesIO
+from zipfile import ZipFile
+
+import requests
+
+
+def current_release():
+    """Returns current version as string from 'git describe' command."""
+    from subprocess import check_output
+
+    _version = check_output(["git", "describe", "--tags", "--always"])
+    if _version:
+        return _version.decode("utf-8")
+    else:
+        return "X.Y"
+
+
+class ArtifactDownloader:
+    """
+    Class used to download Github artifacts.
+
+    Notes
+    -----
+    Adapted from the rtds_action sphinx extension.
+    https://github.com/dfm/rtds-action/blob/main/src/rtds_action/rtds_action.py
+    """
+
+    def __init__(self, repo, prefix="auto_examples-for-"):
+        self.repo = repo
+        self.prefix = prefix
+
+    @staticmethod
+    def current_commit_hash():
+        try:
+            cmd = "git rev-parse HEAD"
+            git_hash = subprocess.check_output(cmd.split(" ")).strip().decode("ascii")
+        except subprocess.CalledProcessError as e:
+            raise RuntimeError(
+                f"Error retrieving git hash. Return code {e.returncode}.\n" + e.stdout
+            )
+        return git_hash
+
+    def available_artifacts(self):
+        request_result = requests.get(
+            f"https://api.github.com/repos/{self.repo}/actions/artifacts",
+            params=dict(per_page=100),
+        )
+
+        if request_result.status_code != 200:
+            raise RuntimeError(
+                f"Error retrieving artifacts: ({request_result.status_code})"
+            )
+        request_result = request_result.json()
+        artifacts = request_result.get("artifacts", [])
+        return artifacts
+
+    def current_hash_artifact(self):
+        commit_hash = self.current_commit_hash()
+        artifact_name = f"{self.prefix}{commit_hash}"
+
+        artifacts = [
+            artifact
+            for artifact in self.available_artifacts()
+            if artifact["name"] == artifact_name
+        ]
+        if len(artifacts) == 0:
+            raise RuntimeError(f"Artifact `{artifact_name}` not found.")
+
+        # Return the first artifact that matches the name. Ignore the rest.
+        return artifacts[0]
+
+    def download_artifact(
+        self, token, dest_dir, retry=3, tar_filename="auto_examples.tar"
+    ):
+        # --- IMPORTANT ----------------------------------------------------------------
+        #
+        # This function uses a GitHub access token to download the artifact.
+        #
+        # To avoid leaking credentials:
+        # - NEVER hardcode the token
+        # - ALWAYS store the token value in environment variables as GitHub secrets
+        #   or Read the docs environmental variables.
+        # - NEVER print or log the token value for debugging
+        # - NEVER print or log the request header since it contains the token.
+        #
+        # For testing:
+        # - Generate a temporary token that expires the next day.
+        # - Remove the temporary token from GitHub once the testing finished.
+        # ------------------------------------------------------------------------------
+        dest_dir = str(dest_dir)
+        artifact = self.current_hash_artifact()
+        for n in range(retry):
+            # Access token needed to download artifacts
+            # https://github.com/actions/upload-artifact/issues/51
+            request_result = requests.get(
+                artifact["archive_download_url"],
+                headers={"Authorization": f"token {token}"},
+            )
+
+            if request_result.status_code != 200:
+                print(
+                    f"Can't download artifact ({request_result.status_code})."
+                    f"Retry {n + 1}/{retry}"
+                )
+                continue
+
+            with tempfile.TemporaryDirectory() as tmp_dir:
+                local_artifact_dir = os.path.join(tmp_dir, "artifact")
+                with ZipFile(BytesIO(request_result.content)) as f:
+                    f.extractall(path=local_artifact_dir)
+
+                _tar_filename = os.path.join(local_artifact_dir, tar_filename)
+                if not os.path.isfile(_tar_filename):
+                    raise RuntimeError(f"{tar_filename} file not found in artifact.")
+
+                my_tar = tarfile.open(_tar_filename)
+                my_tar.extractall(dest_dir)
+            return
+
+        raise RuntimeError(f"Can't download artifact after {retry} retries.")

From a281a45034bda8e54cb9bba29c22f8766bd7157e Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 12:55:06 -0500
Subject: [PATCH 15/27] Only download the artifacts in RTD, otherwise render
 gallery

---
 doc/source/conf.py | 32 +++++++++++++++-----------------
 1 file changed, 15 insertions(+), 17 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 2239cabcf..ea30feca3 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -30,17 +30,14 @@
 release = doc_utils.current_release()
 version = release.lstrip("v").rstrip().split("-")[0]  # The short X.Y version.
 
+is_run_in_read_the_docs = "READTHEDOCS" in os.environ
 sphinx_gallery_conf = {
     "examples_dirs": "../../examples",
     "gallery_dirs": "user_guide/auto_examples",
     "filename_pattern": r"/*\.py",
-    "plot_gallery": True,
+    "plot_gallery": not is_run_in_read_the_docs,
 }
 
-if "READTHEDOCS" in os.environ:
-    # In RTD, we use the rendered examples
-    sphinx_gallery_conf["plot_gallery"] = False
-
 # -- Options for HTML output ----------------------------------------------
 html_theme = "sphinx_book_theme"
 html_title = ""
@@ -67,16 +64,17 @@
 autosummary_generate = True
 htmlhelp_basename = "pystepsdoc"
 
-# -- Download artifacts with rendered examples------------------------------------------
-my_artifact_downloader = doc_utils.ArtifactDownloader(
-    "pySTEPS/pysteps", prefix="auto_examples-for-"
-)
+# -- Download artifacts with rendered examples in RTD ----------------------------------
+if is_run_in_read_the_docs:
+    my_artifact_downloader = doc_utils.ArtifactDownloader(
+        "pySTEPS/pysteps", prefix="auto_examples-for-"
+    )
 
-DOC_ROOT_DIR = Path(__file__).parent / "../"
-token = os.environ.get("RTD_GITHUB_TOKEN")  # never print this!
-my_artifact_downloader.download_artifact(
-    token,
-    DOC_ROOT_DIR / "source/auto_examples",
-    retry=3,
-    tar_filename="auto_examples.tar",
-)
+    DOC_ROOT_DIR = Path(__file__).parent / "../"
+    token = os.environ.get("RTD_GITHUB_TOKEN")  # never print this!
+    my_artifact_downloader.download_artifact(
+        token,
+        DOC_ROOT_DIR / "source/auto_examples",
+        retry=3,
+        tar_filename="auto_examples.tar",
+    )

From 2f2cde5e2eafee4ba09a78cb7e28fbfee0e35d61 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 13:04:06 -0500
Subject: [PATCH 16/27] Add numpydoc to docs requirements

---
 doc/requirements.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/requirements.txt b/doc/requirements.txt
index 05e2450cd..db1d62c62 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,5 +1,6 @@
 # Additional requeriments related to the documentation build only
 sphinx
+numpydoc
 sphinxcontrib.bibtex
 sphinx-book-theme
 sphinx_gallery

From 452363368aabb03f68848ed43cfdd24356f31c69 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 13:10:40 -0500
Subject: [PATCH 17/27] Add requests library to doc requirements

---
 doc/requirements.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/requirements.txt b/doc/requirements.txt
index db1d62c62..dce04b2f2 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,5 +1,6 @@
-# Additional requeriments related to the documentation build only
+# Additional requirements related to the documentation build only
 sphinx
+requests
 numpydoc
 sphinxcontrib.bibtex
 sphinx-book-theme

From 5cb9066636ee72f317c73779fd7b173f470fc632 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 13:35:13 -0500
Subject: [PATCH 18/27] Fix auto-examples dir

---
 doc/source/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index ea30feca3..9c617eb3e 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -33,7 +33,7 @@
 is_run_in_read_the_docs = "READTHEDOCS" in os.environ
 sphinx_gallery_conf = {
     "examples_dirs": "../../examples",
-    "gallery_dirs": "user_guide/auto_examples",
+    "gallery_dirs": "auto_examples",
     "filename_pattern": r"/*\.py",
     "plot_gallery": not is_run_in_read_the_docs,
 }

From 203c01aba0db1c500b96d5168a75e926583860c8 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 5 Feb 2022 13:54:46 -0500
Subject: [PATCH 19/27] Fix docstrings

---
 pysteps/verification/spatialscores.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pysteps/verification/spatialscores.py b/pysteps/verification/spatialscores.py
index afce35ee4..243ee9f21 100644
--- a/pysteps/verification/spatialscores.py
+++ b/pysteps/verification/spatialscores.py
@@ -368,7 +368,7 @@ def binary_mse_accum(bmse, X_f, X_o):
     """Accumulate forecast-observation pairs to an BMSE object.
 
     Parameters
-    -----------
+    ----------
     bmse: dict
         The BMSE object initialized with
         :py:func:`pysteps.verification.spatialscores.binary_mse_init`.
@@ -577,7 +577,7 @@ def fss_accum(fss, X_f, X_o):
     """Accumulate forecast-observation pairs to an FSS object.
 
     Parameters
-    -----------
+    ----------
     fss: dict
         The FSS object initialized with
         :py:func:`pysteps.verification.spatialscores.fss_init`.

From 793341d3a7ed430759367518a4e461fe224ba093 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sun, 6 Feb 2022 13:26:01 -0500
Subject: [PATCH 20/27] Add RTD manual trigger

---
 .github/workflows/render_example_gallery.yml | 97 ++++++++++++++++----
 1 file changed, 77 insertions(+), 20 deletions(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index 9eb68698c..17a79b41d 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -1,9 +1,32 @@
 # Execute the examples, in the form of python scripts, and render the examples
 # using sphinx-gallery. Then, trigger ReadTheDocs.
-
+#
 # Workflow inspired by the https://github.com/dfm/rtds-action project and the
 # following wradlib-notebooks CI task:
 # https://github.com/wradlib/wradlib-notebooks/blob/main/.github/workflows/main.yml
+#
+# Steps needed to setup this workflow
+# ===================================
+#
+# Read-the-docs configuration
+# ---------------------------
+#
+# 1. In Admin/Integrations, add a generic API incoming webhook.
+#    Save the webhook url and token value.
+# 2. Add the RTD_GITHUB_TOKEN environmental variable in RTD (Settings/Environment Variables)
+#    with the pysteps-bot's Github access token. This access token should only
+#    have the "public_repo" scope.
+#    At the moment, this token is needed to download the artifacts in RTD's.
+#
+# Github configuration
+# ---------------------
+#
+# 1. Add the following secrets to the pysteps repository:
+# - RTD_WEBHOOK_URL: Read-the-docs webhook. Important: the RTD-Github integration
+#   must not be activated since this workflow triggers the RTD build.
+# - RTD_TOKEN: RTD webhook access token.
+#
+
 name: Render the example gallery
 
 on:
@@ -74,22 +97,56 @@ jobs:
           name: auto_examples-for-${{ github.sha }}
           path: auto_examples.tar
 
-#  trigger_rtd:
-#    # Task adapted from the wradlib project
-#    # https://github.com/wradlib/wradlib-notebooks/blob/main/.github/workflows/render_notebooks.yml
-#    needs: [ run_notebooks ]
-#    name: Trigger readthedocs
-#    runs-on: ubuntu-latest
-#    defaults:
-#      run:
-#        shell: bash -l {0}
-#    env:
-#      RTD_TOKEN: ${{ secrets.PYSTEPS_BOT_RTD_TOKEN }}
-#      RTD_URL: ${{ secrets.RTD_URL }}
-#      RTD_BRANCH: ${{steps.parse_commit_msg.outputs.rtd_branch}}
-#    steps:
-#      - name: Trigger readthedocs for the corresponding branch (latest or tag)
-#        run: |
-#          if [[ ! -z "${RTD_BRANCH}" ]]; then
-#            curl -X POST -d "branches=${RTD_BRANCH}" -d "token=${RTD_TOKEN}" "${RTD_URL}"
-#          fi
+  trigger_rtd:
+    # Task adapted from the wradlib project
+    # https://github.com/wradlib/wradlib-notebooks/blob/main/.github/workflows/render_notebooks.yml
+    needs: [ render_example_gallery ]
+    name: Trigger readthedocs
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - name: Get the name of the branch triggering this event
+        id: get_triggering_branch
+        run: |
+          if [[ "${GITHUB_EVENT_NAME}" == "push" ]]; then
+            triggering_branch=$(echo ${GITHUB_REF##*/})
+          elif [[ "${GITHUB_EVENT_NAME}" == "pull_request" ]]; then
+            triggering_branch=$(echo $GITHUB_BASE_REF)
+          else
+            triggering_branch=unknown
+          fi
+          echo "::set-output name=triggering_branch::${triggering_branch}"
+
+      - name: Determine rendered branch name
+        id: set_rtd_branch
+        env:
+          triggering_branch: ${{steps.get_triggering_branch.outputs.triggering_branch}}
+        run: |
+          tag_name=$(git name-rev --name-only --tags HEAD)
+          if [[ "${tag_name}" != "undefined" ]]; then 
+            rtd_branch="${tag_name}"
+          else
+            rtd_branch="${triggering_branch}"
+          fi
+          
+          echo "::set-output name=rtd_branch::${rtd_branch}"
+
+      - name: Print debug information
+        env:
+          triggering_branch: ${{steps.get_triggering_branch.outputs.triggering_branch}}
+          rtd_branch: ${{steps.set_rtd_branch.outputs.rtd_branch}}
+        run: |
+          echo "triggering_branch=${triggering_branch}"
+          echo "rtd_branch=${rtd_branch}"
+
+      - name: Trigger readthedocs for the corresponding branch (latest or tag)
+        env:
+          RTD_TOKEN: ${{ secrets.RTD_TOKEN }}
+          RTD_WEBHOOK_URL: ${{ secrets.RTD_WEBHOOK_URL }}
+          RTD_BRANCH: ${{steps.set_rtd_branch.outputs.rtd_branch}}
+        run: |
+          if [[ ! -z "${RTD_BRANCH}" ]]; then
+            curl -X POST -d "branches=${RTD_BRANCH}" -d "token=${RTD_TOKEN}" "${RTD_WEBHOOK_URL}"
+          fi

From 7f29bc7497c0767376a6260fa26aebcaedfe63a3 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sun, 6 Feb 2022 13:31:40 -0500
Subject: [PATCH 21/27] Update repo URL temporary to work on the fork

---
 doc/source/conf.py | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 9c617eb3e..8db89df30 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -7,6 +7,9 @@
 sys.path.insert(0, str(Path(__file__).parent))
 import doc_utils
 
+# REPO_URL="pySTEPS/pysteps"
+REPO_URL="aperezhortal/pysteps"
+
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
@@ -49,7 +52,7 @@
 }
 
 html_theme_options = {
-    "repository_url": "https://github.com/pySTEPS/pysteps",
+    "repository_url": f"https://github.com/{REPO_URL}",
     "repository_branch": "master",
     "path_to_docs": "doc/source",
     "use_edit_page_button": True,
@@ -67,7 +70,7 @@
 # -- Download artifacts with rendered examples in RTD ----------------------------------
 if is_run_in_read_the_docs:
     my_artifact_downloader = doc_utils.ArtifactDownloader(
-        "pySTEPS/pysteps", prefix="auto_examples-for-"
+        REPO_URL, prefix="auto_examples-for-"
     )
 
     DOC_ROOT_DIR = Path(__file__).parent / "../"

From 799ea46c2d11a8b009001114b5f38c8e8f033c64 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sun, 6 Feb 2022 14:27:53 -0500
Subject: [PATCH 22/27] Fix RTD destination branch

---
 .github/workflows/render_example_gallery.yml | 33 ++++++++------------
 1 file changed, 13 insertions(+), 20 deletions(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index 17a79b41d..a098f418e 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -35,6 +35,8 @@ on:
     branches: [ master, rtd_using_gh_artifacts ]
   pull_request:
     branches: [ master ]
+  release:
+    types: [ published ]
 
 jobs:
   render_example_gallery:
@@ -107,38 +109,29 @@ jobs:
       run:
         shell: bash -l {0}
     steps:
-      - name: Get the name of the branch triggering this event
-        id: get_triggering_branch
+      - name: Determine rendered branch name
+        id: set_rtd_branch
         run: |
           if [[ "${GITHUB_EVENT_NAME}" == "push" ]]; then
-            triggering_branch=$(echo ${GITHUB_REF##*/})
+            rtd_branch="${GITHUB_REF##*/}"
           elif [[ "${GITHUB_EVENT_NAME}" == "pull_request" ]]; then
-            triggering_branch=$(echo $GITHUB_BASE_REF)
+            rtd_branch=$GITHUB_BASE_REF
+          elif [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            rtd_branch="${GITHUB_REF_NAME}"
           else
-            triggering_branch=unknown
+            rtd_branch="undefined"
           fi
-          echo "::set-output name=triggering_branch::${triggering_branch}"
 
-      - name: Determine rendered branch name
-        id: set_rtd_branch
-        env:
-          triggering_branch: ${{steps.get_triggering_branch.outputs.triggering_branch}}
-        run: |
-          tag_name=$(git name-rev --name-only --tags HEAD)
-          if [[ "${tag_name}" != "undefined" ]]; then 
-            rtd_branch="${tag_name}"
-          else
-            rtd_branch="${triggering_branch}"
-          fi
-          
           echo "::set-output name=rtd_branch::${rtd_branch}"
 
       - name: Print debug information
         env:
-          triggering_branch: ${{steps.get_triggering_branch.outputs.triggering_branch}}
           rtd_branch: ${{steps.set_rtd_branch.outputs.rtd_branch}}
         run: |
-          echo "triggering_branch=${triggering_branch}"
+          echo "GITHUB_REF=${GITHUB_REF}"
+          echo "GITHUB_REF_TYPE=${GITHUB_REF_TYPE}"
+          echo "GITHUB_REF_NAME=${GITHUB_REF_NAME}"
+          echo "GITHUB_EVENT_NAME=${GITHUB_EVENT_NAME}"
           echo "rtd_branch=${rtd_branch}"
 
       - name: Trigger readthedocs for the corresponding branch (latest or tag)

From 1e3b617d0558c47415a6c1e4a0109a6b5c03f3fd Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sun, 6 Feb 2022 15:14:13 -0500
Subject: [PATCH 23/27] Update pre-commit hook config

---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c80571951..6ab8e1c23 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 repos:
 -   repo: https://github.com/psf/black
-    rev: 21.6b0
+    rev: 22.1.0
     hooks:
     - id: black
       language_version: python3
\ No newline at end of file

From 359680fdbe0c908e6b88cb931c4d4b5123ee5e10 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sun, 6 Feb 2022 15:15:21 -0500
Subject: [PATCH 24/27] Stylistic adjustments

---
 .github/workflows/render_example_gallery.yml | 15 +++++++--------
 doc/source/conf.py                           |  2 +-
 2 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index a098f418e..1fbd30eed 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -1,9 +1,9 @@
-# Execute the examples, in the form of python scripts, and render the examples
-# using sphinx-gallery. Then, trigger ReadTheDocs.
+# Action to render the example gallery, upload them as artifacts. After the examples are
+# rendered, the ReadTheDocs build is triggered pulling the artifacts with the rendered
+# example gallery.
 #
-# Workflow inspired by the https://github.com/dfm/rtds-action project and the
-# following wradlib-notebooks CI task:
-# https://github.com/wradlib/wradlib-notebooks/blob/main/.github/workflows/main.yml
+# This workflow is inspired by the actions in the https://github.com/dfm/rtds-action and
+# https://github.com/wradlib/wradlib-notebooks projects.
 #
 # Steps needed to setup this workflow
 # ===================================
@@ -25,7 +25,6 @@
 # - RTD_WEBHOOK_URL: Read-the-docs webhook. Important: the RTD-Github integration
 #   must not be activated since this workflow triggers the RTD build.
 # - RTD_TOKEN: RTD webhook access token.
-#
 
 name: Render the example gallery
 
@@ -100,7 +99,7 @@ jobs:
           path: auto_examples.tar
 
   trigger_rtd:
-    # Task adapted from the wradlib project
+    # Task inspired in the following wradlib's action:
     # https://github.com/wradlib/wradlib-notebooks/blob/main/.github/workflows/render_notebooks.yml
     needs: [ render_example_gallery ]
     name: Trigger readthedocs
@@ -134,7 +133,7 @@ jobs:
           echo "GITHUB_EVENT_NAME=${GITHUB_EVENT_NAME}"
           echo "rtd_branch=${rtd_branch}"
 
-      - name: Trigger readthedocs for the corresponding branch (latest or tag)
+      - name: Trigger readthedocs for the corresponding branch
         env:
           RTD_TOKEN: ${{ secrets.RTD_TOKEN }}
           RTD_WEBHOOK_URL: ${{ secrets.RTD_WEBHOOK_URL }}
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 8db89df30..11d1ff1df 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -8,7 +8,7 @@
 import doc_utils
 
 # REPO_URL="pySTEPS/pysteps"
-REPO_URL="aperezhortal/pysteps"
+REPO_URL = "aperezhortal/pysteps"
 
 extensions = [
     "sphinx.ext.autodoc",

From 933ecece0a29c8a69607e1070ad2ea5bdecf279d Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 26 Feb 2022 09:04:19 -0500
Subject: [PATCH 25/27] Abort documentation build examples error

---
 doc/source/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 11d1ff1df..b9fca144f 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -39,6 +39,7 @@
     "gallery_dirs": "auto_examples",
     "filename_pattern": r"/*\.py",
     "plot_gallery": not is_run_in_read_the_docs,
+    "abort_on_example_error": True
 }
 
 # -- Options for HTML output ----------------------------------------------

From adec505792e4e247b3a6eb8c8bb862f6810c1052 Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 26 Feb 2022 09:51:14 -0500
Subject: [PATCH 26/27] Save conda environment in artifact

---
 .github/workflows/render_example_gallery.yml | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index 1fbd30eed..dd699778f 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -32,8 +32,8 @@ on:
   # Triggers the workflow on push or pull request events to the master branch
   push:
     branches: [ master, rtd_using_gh_artifacts ]
-  pull_request:
-    branches: [ master ]
+#  pull_request:
+#    branches: [ master ]
   release:
     types: [ published ]
 
@@ -88,6 +88,10 @@ jobs:
         run: |
           make html       
 
+      - name: Export conda environment
+        working-directory: ./doc
+        run: conda env export > doc/source/auto_examples/environment.yml
+
       - name: Tar auto_examples files
         # Needed to maintain permissions and case-sensitive files
         # https://github.com/actions/upload-artifact#maintaining-file-permissions-and-case-sensitive-files

From dc46166ae6311780f5e66606a0e46de734337f6c Mon Sep 17 00:00:00 2001
From: Andres Perez Hortal <16256571+aperezhortal@users.noreply.github.com>
Date: Sat, 26 Feb 2022 10:13:53 -0500
Subject: [PATCH 27/27] Fix export path

---
 .github/workflows/render_example_gallery.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/render_example_gallery.yml b/.github/workflows/render_example_gallery.yml
index dd699778f..63bbd8ea7 100644
--- a/.github/workflows/render_example_gallery.yml
+++ b/.github/workflows/render_example_gallery.yml
@@ -89,7 +89,6 @@ jobs:
           make html       
 
       - name: Export conda environment
-        working-directory: ./doc
         run: conda env export > doc/source/auto_examples/environment.yml
 
       - name: Tar auto_examples files