Enable selective example build

Update conf.py to allow limited scope for building examples. Look for environment variables "EXAMPLES_DIR" and "EXAMPLE_FILE".

See workflow/build_examples.yml for further details.

.github/workflows/build_examples.yml

@@ -6,6 +6,12 @@ env:
   RESET_EXAMPLES_CACHE: 3
   RESET_DOC_BUILD_CACHE: 3
   RESET_AUTOSUMMARY_CACHE: 3
+  # Use the following env variables to limit which examples will be built. If these
+  # values are not set, the full examples directory will be parsed and run.
+  EXAMPLES_DIR: '02-HFSS'
+  # The following env variable may also be a regex that is used to select
+  # the example files that will be run.
+  EXAMPLE_FILE: 'Array.py'
 
 # Controls when the workflow will run
 on:

doc/source/conf.py

@@ -266,18 +266,31 @@ def setup(app):
     # necessary for pyvista when building the sphinx gallery
     pyvista.BUILDING_GALLERY = True
 
+    examples_dir = "../../examples"
+    gallery_dir = "examples"
+    filename_pattern = r"\.py"
     if config["run_examples"]:
         extensions.append("sphinx_gallery.gen_gallery")
-
+        # The environment variable "EXAMPLES_FOLDER" can be used
+        # to limit which directories should be run to create the
+        # gallery examples.
+        if "EXAMPLES_DIR" in os.environ.keys():
+            examples_dir = os.path.join(examples_dir, os.environ["EXAMPLES_DIR"])
+            gallery_dir = os.path.join(gallery_dir, os.environ["EXAMPLES_DIR"])
+            if "EXAMPLE_FILE" in os.environ.keys():
+                filename_pattern = os.environ["EXAMPLE_FILE"]
         sphinx_gallery_conf = {
             # convert rst to md for ipynb
             "pypandoc": True,
             # path to your examples scripts
-            "examples_dirs": ["../../examples/"],
+            "examples_dirs": [examples_dir],
             # path where to save gallery generated examples
-            "gallery_dirs": ["examples"],
+            "gallery_dirs": [gallery_dir],
             # Patter to search for examples files
-            "filename_pattern": r"\.py",
+            "filename_pattern": filename_pattern,
+            # Allow py:percent format for example files to allow editing directly in a jupyter
+            # notebook using the jupytext plugin. 'doctest' is the default for *.py files.
+            "sphinx_gallery_formats": ["doctest", "py:percent"],
             # Remove the "Download all examples" button from the top level gallery
             "download_all_examples": False,
             # Sort gallery examples by file name instead of number of lines (default)