From 3e3286c07b4e627dde26325db4ca8ab8472a3feb Mon Sep 17 00:00:00 2001 From: Devin Date: Sun, 3 Dec 2023 20:23:13 +0100 Subject: [PATCH] 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 ++++++ doc/source/conf.py | 21 +++++++++++++++++---- 2 files changed, 23 insertions(+), 4 deletions(-) diff --git a/.github/workflows/build_examples.yml b/.github/workflows/build_examples.yml index 110b85a1fd5..ba483adca00 100644 --- a/.github/workflows/build_examples.yml +++ b/.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: diff --git a/doc/source/conf.py b/doc/source/conf.py index 864471ad0ff..91e29dd5c1c 100644 --- a/doc/source/conf.py +++ b/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)