Update figure selection and layout of the gallery

doc/sphinx/source/generate_gallery.py

@@ -2,6 +2,7 @@
 """Create gallery with all available recipes."""
 
 import os
+from pathlib import Path
 
 RECIPE_DIR = "recipes"
 OUT_PATH = os.path.abspath("gallery.rst")
@@ -31,10 +32,14 @@
 
 def _get_figure_index(file_content):
     """Get index of figure in text."""
+    offset = 0
+    if ".. gallery=True" in file_content:
+        offset = file_content.index(".. gallery=True") + 15
+        file_content = file_content[offset:]
     if FIGURE_STR in file_content:
-        return file_content.index(FIGURE_STR) + len(FIGURE_STR)
+        return offset + file_content.index(FIGURE_STR) + len(FIGURE_STR)
     if IMAGE_STR in file_content:
-        return file_content.index(IMAGE_STR) + len(IMAGE_STR)
+        return offset + file_content.index(IMAGE_STR) + len(IMAGE_STR)
     raise ValueError("File does not contain image")
 
 
@@ -79,6 +84,17 @@ def _get_next_row(filenames, file_contents):
     return (row, refs)
 
 
+def _find_recipes(root_dir, exclude_dirs):
+    return [
+        path.relative_to(root_dir)
+        for path in Path(root_dir).rglob("recipe_*.rst")
+        if not any(
+            path.parents[0].name.startswith(exclude)
+            for exclude in exclude_dirs
+        )
+    ]
+
+
 def main():
     """Generate gallery for recipe plots."""
     print(f"Generating gallery at {OUT_PATH}")
@@ -87,11 +103,8 @@ def main():
     refs = ""
     filenames = []
     file_contents = []
-    for filename in sorted(os.listdir(RECIPE_DIR)):
-        if not filename.startswith("recipe_"):
-            continue
-        if not filename.endswith(".rst"):
-            continue
+    fnames = _find_recipes(RECIPE_DIR, ["legacy", "figures"])
+    for filename in sorted(fnames):
         with open(os.path.join(RECIPE_DIR, filename)) as in_file:
             recipe_file = in_file.read()
         if FIGURE_STR not in recipe_file and IMAGE_STR not in recipe_file:

doc/sphinx/source/recipes/index.rst

@@ -107,7 +107,6 @@ IPCC
    recipe_ipccwg1ar6ch3
    recipe_ipccwg1ar5ch9
    recipe_collins13ipcc
-   recipe_examples
 
 Land
 ^^^^
@@ -165,11 +164,10 @@ require a legacy version of ESMValTool to run.
 
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
+
+   legacy_recipe_list
 
-   recipe_rainfarm
-   recipe_schlund20jgr
-   recipe_spei
 
 
 Broken recipe list

doc/sphinx/source/recipes/legacy_recipe_list.rst

@@ -0,0 +1,15 @@
+.. _legacy_recipe_list:
+
+Legacy Recipes
+==============
+
+Recipes that have been retired and are included for
+documentation purposes only. Typically, these recipes
+require a legacy version of ESMValTool to run.
+
+.. toctree::
+   :maxdepth: 1
+
+   legacy/recipe_rainfarm
+   legacy/recipe_schlund20jgr
+   legacy/recipe_spei

doc/sphinx/source/recipes/recipe_gier20bg.rst

@@ -193,6 +193,7 @@ Example plots
    Barplot of the growth rate, averaged over all years, with standard deviation
    of interannual variability.
 
+.. gallery=True
 .. _fig_gier20bg_5:
 .. figure::  /recipes/figures/gier20bg/fig05.png
    :align:   center