Decouple recipes gallery from main docs build

docs/source/conf.py

@@ -18,7 +18,6 @@
 import sys
 
 import cfdm
-from sphinx_gallery.sorting import FileNameSortKey
 
 import cf
 
@@ -103,11 +102,6 @@ def _get_date():
     "sphinxcontrib.spelling",
 ]
 
-CF_DOCS_MODE = os.environ.get("CF_DOCS_MODE", "none")
-
-if CF_DOCS_MODE in ["dev-recipes", "dev-recipes-scrub", "latest", "archive"]:
-    extensions.append("sphinx_gallery.gen_gallery")
-
 # Spelling extension configuration: set British English and false positives
 spelling_lang = "en_GB"
 tokenizer_lang = "en_GB"
@@ -382,26 +376,6 @@ def _get_date():
 # Output file base name for HTML help builder.
 htmlhelp_basename = "cfdoc"
 
-# sphinx-gallery configuration
-sphinx_gallery_conf = {
-    "examples_dirs": "recipes",  # path to recipe files
-    "gallery_dirs": "recipes",  # path to save gallery generated output
-    "run_stale_examples": False,
-    # Below setting can be buggy: see:
-    # https://github.com/sphinx-gallery/sphinx-gallery/issues/967
-    # "reference_url": {"cf": None},
-    "backreferences_dir": "gen_modules/backreferences",
-    "doc_module": ("cf",),
-    "inspect_global_variables": True,
-    "within_subsection_order": FileNameSortKey,
-    "default_thumb_file": "_static/cf-recipe-placeholder-squarecrop.png",
-    "image_scrapers": (
-        "matplotlib",
-    ),  # Ensures Matplotlib images are captured
-    "plot_gallery": True,  # Enables plot rendering
-    "reset_modules": ("matplotlib",),  # Helps with memory management
-    "capture_repr": (),
-}
 
 import warnings
 

pyproject.toml

@@ -22,5 +22,5 @@ line_length=79
 # which can cause a seg fault if cf-plot/matplotlib is imported first.
 extend_skip_glob = [
   "**/__init__.py",
-  "docs/source/recipes/**",
+  "recipes-docs/source/recipes/**",
 ]

recipes-docs/Makefile

@@ -0,0 +1,139 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -j 1
+SPHINXBUILD   = sphinx-build
+PAPER         =
+#BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+#ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   =  $(SPHINXOPTS) source
+BUILDDIR        = $(filter-out $@, $(MAKECMDGOALS))
+
+
+.PHONY: help clean html spelling dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	$(if $(BUILDDIR),,$(error BUILDDIR to clean must be defined))
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)"
+
+spelling:
+	$(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) $(BUILDDIR)/spelling
+	@echo
+	@echo "Spelling check dummy finished. Results are in $(BUILDDIR)/spelling."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/y.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/y.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/y"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/y"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

recipes-docs/source/conf.py

@@ -0,0 +1,43 @@
+import os
+import sys
+
+from sphinx_gallery.sorting import FileNameSortKey
+
+# Make main 'docs' conf.py importable
+sys.path.insert(0, os.path.abspath("../../docs/source"))
+
+# Import everything from the main docs configuration
+from conf import *  # noqa: F403
+
+# Now update the main docs configuration for recipes-specific needs
+# TODO
+# CF_DOCS_MODE = os.environ.get("CF_DOCS_MODE", "none")
+# if CF_DOCS_MODE in ["dev-recipes", "dev-recipes-scrub", "latest", "archive"]:
+
+# We need to use and configure sphinx-gallery for the recipes
+extensions.append("sphinx_gallery.gen_gallery")  # noqa: F405
+
+# sphinx-gallery configuration
+sphinx_gallery_conf = {
+    "examples_dirs": "recipes",  # path to recipe files
+    "gallery_dirs": "recipes",  # path to save gallery generated output
+    "run_stale_examples": False,
+    # Below setting can be buggy: see:
+    # https://github.com/sphinx-gallery/sphinx-gallery/issues/967
+    # "reference_url": {"cf": None},
+    "backreferences_dir": "gen_modules/backreferences",
+    "doc_module": ("cf",),
+    "inspect_global_variables": True,
+    "within_subsection_order": FileNameSortKey,
+    "default_thumb_file": "_static/cf-recipe-placeholder-squarecrop.png",
+    "image_scrapers": (
+        "matplotlib",
+    ),  # Ensures Matplotlib images are captured
+    "plot_gallery": True,  # Enables plot rendering
+    "reset_modules": ("matplotlib",),  # Helps with memory management
+    "capture_repr": (),
+}
+
+html_static_path = ["../../docs/source/_static"]
+html_logo = "../../docs/source/images/logo.svg"
+html_favicon = "../../docs/source/_static/favicon.ico"

recipes-docs/source/index.rst

@@ -0,0 +1,95 @@
+:orphan:
+
+**Recipes using cf**
+====================
+
+----
+
+Version |release| for version |version| of the CF conventions.
+
+Click on the keywords below to filter the recipes according to their function:
+
+.. raw:: html
+
+   <script>
+   document.addEventListener('DOMContentLoaded', function() {
+       showFilteredRecipes('all');
+
+       function showFilteredRecipes(filter) {
+           const recipes = document.querySelectorAll('.sphx-glr-thumbcontainer');
+           recipes.forEach(recipe => {
+               if (filter === 'all') {
+                   recipe.style.display = 'inline-block';
+               } else if (recipe.classList.contains(filter)) {
+                   recipe.style.display = 'inline-block';
+               } else {
+                   recipe.style.display = 'none';
+               }
+           });
+       }
+
+       const filterButtons = document.querySelectorAll('.filter-menu button');
+       filterButtons.forEach(button => {
+           button.addEventListener('click', () => {
+               const filter = button.getAttribute('data-filter');
+               showFilteredRecipes(filter);
+           });
+       });
+   });
+   </script>
+
+.. raw:: html
+
+   <style>
+      .filter-menu {
+          margin-bottom: 20px;
+      }
+   </style>
+
+   <div class="filter-menu">
+       <button data-filter="all">All</button>
+       <button data-filter="aggregate">Aggregate</button>
+       <button data-filter="collapse">Collapse</button>
+       <button data-filter="contourmap">Contourmap</button>
+       <button data-filter="histogram">Histogram</button>
+       <button data-filter="lineplot">Lineplot</button>
+       <button data-filter="maths">Mathematical Operations</button>
+       <button data-filter="regrid">Regrid</button>
+       <button data-filter="subspace">Subspace</button>
+       <button data-filter="mask">Mask</button>
+       <button data-filter="vectorplot">Vectorplot</button>
+       <button data-filter="subplot">Subplot</button>
+       <button data-filter="stats">Statistical Operations</button>
+   </div>
+
+.. raw:: html
+
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbnails">
+
+
+.. raw:: html
+
+    </div>
+
+
+.. only:: html
+
+  .. container:: sphx-glr-footer sphx-glr-footer-gallery
+
+    .. container:: sphx-glr-download sphx-glr-download-python
+
+      :download:`Download all examples in Python source code: recipes_python.zip </recipes/recipes_python.zip>`
+
+    .. container:: sphx-glr-download sphx-glr-download-jupyter
+
+      :download:`Download all examples in Jupyter notebooks: recipes_jupyter.zip </recipes/recipes_jupyter.zip>`
+
+
+.. only:: html
+
+ .. rst-class:: sphx-glr-signature
+
+    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_

recipes-docs/source/recipes/images/index.rst

@@ -0,0 +1,22 @@
+
+
+.. _sphx_glr_recipes_images:
+
+
+
+
+
+
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbnails">
+
+.. thumbnail-parent-div-open
+
+.. thumbnail-parent-div-close
+
+.. raw:: html
+
+    </div>
+

recipes-docs/source/recipes/images/sg_execution_times.rst

@@ -0,0 +1,37 @@
+
+:orphan:
+
+.. _sphx_glr_recipes_images_sg_execution_times:
+
+
+Computation times
+=================
+**00:00.000** total execution time for 0 files **from recipes/images**:
+
+.. container::
+
+  .. raw:: html
+
+    <style scoped>
+    <link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/5.3.0/css/bootstrap.min.css" rel="stylesheet" />
+    <link href="https://cdn.datatables.net/1.13.6/css/dataTables.bootstrap5.min.css" rel="stylesheet" />
+    </style>
+    <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
+    <script src="https://cdn.datatables.net/1.13.6/js/jquery.dataTables.min.js"></script>
+    <script src="https://cdn.datatables.net/1.13.6/js/dataTables.bootstrap5.min.js"></script>
+    <script type="text/javascript" class="init">
+    $(document).ready( function () {
+        $('table.sg-datatable').DataTable({order: [[1, 'desc']]});
+    } );
+    </script>
+
+  .. list-table::
+   :header-rows: 1
+   :class: table table-striped sg-datatable
+
+   * - Example
+     - Time
+     - Mem (MB)
+   * - N/A
+     - N/A
+     - N/A