feat: enable matplotlib and plotly in examples

.pre-commit-config.yaml

@@ -11,6 +11,7 @@ repos:
   rev: v2.3.0
   hooks:
   - id: codespell
+    exclude: doc/source/examples/nbsphinx/jupyter-notebook.ipynb
 
 - repo: https://github.com/pre-commit/mirrors-prettier
   rev: 'v4.0.0-alpha.8'

doc/changelog.d/567.added.md

@@ -0,0 +1 @@
+feat: enable matplotlib and plotly in examples

doc/source/conf.py

@@ -3,11 +3,12 @@
 from datetime import datetime
 import os
 from pathlib import Path
-from typing import List
+from typing import Dict, List
 
 from github import Github
 import pyvista
 import requests
+from sphinx.application import Sphinx
 from sphinx.builders.latex import LaTeXBuilder
 
 from ansys_sphinx_theme import (
@@ -133,8 +134,8 @@
 exclude_patterns = [
     "links.rst",
     "examples/sphinx-gallery/README.rst",
-    "examples/gallery-examples/*.ipynb",
     "sg_execution_times.rst",
+    "examples/gallery-examples/*.ipynb",
 ]
 rst_epilog = ""
 with Path.open(THIS_PATH / "links.rst", "r") as f:
@@ -180,7 +181,8 @@ def extract_example_links(
     list
         List of example links.
     """
-    g = Github()
+    token = os.getenv("GITHUB_TOKEN")
+    g = Github(token)
     repo = g.get_repo(repo_fullname)
     contents = repo.get_contents(path_relative_to_root)
     if not isinstance(contents, list):
@@ -233,8 +235,6 @@ def download_and_process_files(example_links: List[str]) -> List[str]:
 
 if not BUILD_EXAMPLES:
     exclude_patterns.extend(["examples.rst", "examples/**", "examples/api/**"])
-
-
 else:
     # Autoapi examples
     extensions.append("ansys_sphinx_theme.extension.autoapi")
@@ -245,35 +245,38 @@ def download_and_process_files(example_links: List[str]) -> List[str]:
         "own_page_level": "function",
         "package_depth": 1,
     }
+    try:
+        import plotly
+        import plotly.io
+    except ImportError:
+        plotly = None
 
     # Gallery of examples
     extensions.extend(["nbsphinx", "sphinx_gallery.gen_gallery"])
     sphinx_gallery_conf = {
         # path to your examples scripts
-        "examples_dirs": ["examples/sphinx-gallery"],
+        "examples_dirs": ["examples/sphinx-gallery/"],
         # path where to save gallery generated examples
-        "gallery_dirs": ["examples/gallery-examples"],
+        "gallery_dirs": ["examples/gallery-examples/"],
         # Pattern to search for example files
-        "filename_pattern": r"sphinx_gallery\.py",
+        "filename_pattern": r"\.py",
         # Remove the "Download all examples" button from the top level gallery
         "download_all_examples": False,
         # Modules for which function level galleries are created.  In
-        "image_scrapers": ("pyvista", "matplotlib"),
-        "default_thumb_file": "source/_static/pyansys_light_square.png",
+        "image_scrapers": ("matplotlib", "pyvista"),
     }
+    pyvista.BUILDING_GALLERY = True
+    pyvista.OFF_SCREEN = True
 
     nbsphinx_prolog = """
 Download this example as a :download:`Jupyter notebook </{{ env.docname }}.ipynb>`.
 
 ----
 """
-    nbsphinx_execute = "always"
     nbsphinx_thumbnails = {
         "examples/nbsphinx/jupyter-notebook": "_static/pyansys_light_square.png",
     }
 
-    pyvista.BUILDING_GALLERY = True
-
     # Third party examples
     example_links = extract_example_links(
         "executablebooks/sphinx-design",
@@ -292,3 +295,30 @@ def download_and_process_files(example_links: List[str]) -> List[str]:
 
     jinja_contexts["examples"] = {"inputs_examples": file_names}
     jinja_contexts["admonitions"] = {"inputs_admonitions": admonitions_links}
+
+
+def revert_exclude_patterns(app, env):
+    """Revert the exclude patterns.
+
+    Parameters
+    ----------
+    app : Sphinx
+        Sphinx application instance.
+    env : BuildEnvironment
+        The build environment.
+
+    Notes
+    -----
+    Remove the examples/gallery-examples/*.ipynb pattern from the exclude patterns.
+    When the nbsphinx extension is enabled, the exclude patterns are modified
+    to exclude the examples/gallery-examples/*.ipynb pattern. This function reverts
+    the exclude patterns to their original state.
+    """
+    excluded_pattern = env.config.exclude_patterns
+    excluded_pattern.remove("examples/gallery-examples/*.ipynb")
+    env.config.exclude_patterns = excluded_pattern
+
+
+def setup(app: Sphinx) -> Dict:
+    """Sphinx hooks to add to the setup."""
+    app.connect("env-updated", revert_exclude_patterns)

doc/source/examples/sphinx-gallery/sphinx-gallery.py

@@ -62,6 +62,44 @@
 plotter.title = "3D Sphere Visualization"
 plotter.show()
 
+###############################################################################
+# Figures with Matplotlib
+# ~~~~~~~~~~~~~~~~~~~~~~~
+# This example shows how to render a figure using Matplotlib.
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+time = np.linspace(0, 2 * np.pi, 100)
+
+fig, ax = plt.subplots()
+ax.plot(time, np.cos(time), color="blue", label=r"$\cos{(t)}$")
+ax.plot(time, np.sin(time), color="red", label=r"$\sin{(t)}$")
+
+ax.set_xlabel("Time [time units]")
+ax.set_ylabel("Amplitude [distance units]")
+ax.set_title("Trigonometric functions")
+
+plt.show()
+
+###############################################################################
+# Figures with Plotly
+# ~~~~~~~~~~~~~~~~~~~
+# This example shows how to render a figure using Plotly.
+
+import plotly.graph_objs as go
+
+# More info: https://plotly.com/python/renderers/
+
+time = np.linspace(0, 2 * np.pi, 100)
+
+cos_trace = go.Scatter(x=time, y=np.cos(time), mode="lines", name="cos(t)")
+sin_trace = go.Scatter(x=time, y=np.sin(time), mode="lines", name="sin(t)")
+
+fig = go.Figure(data=[cos_trace, sin_trace])
+
+fig
+
 ###############################################################################
 # Render equations using IPython ``math``
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -80,18 +118,22 @@
 Latex(r"This is a \LaTeX{} equation: $a^2 + b^2 = c^2$")
 
 ###############################################################################
-# Render a table in markdown
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~
-# This is an example to render a table inside the markdown with Sphinx-Gallery.
+# Render a table
+# ~~~~~~~~~~~~~~
+# This is an example to render a table with Sphinx-Gallery.
+#
+# +--------------------------------+--------------------------------+------------------------------+
+# | A                              | B                              | A and B                      |
+# +================================+================================+==============================+
+# | False                          | False                          | False                        |
+# +--------------------------------+--------------------------------+------------------------------+
+# | True                           | False                          | False                        |
+# +--------------------------------+--------------------------------+------------------------------+
+# | False                          | True                           | False                        |
+# +--------------------------------+--------------------------------+------------------------------+
+# | True                           | True                           | True                         |
+# +--------------------------------+--------------------------------+------------------------------+
 #
-# ====== ====== =======
-# A      B      A and B
-# ====== ====== =======
-# False  False  False
-# True   False  False
-# False  True   False
-# True   True   True
-# ====== ====== =======
 
 ###############################################################################
 # Render a table using pandas
@@ -112,3 +154,5 @@
 df.head()
 
 ###############################################################################
+
+# %%

pyproject.toml

@@ -38,11 +38,13 @@ autoapi = [
 ]
 doc = [
     "jupytext==1.16.4",
+    "matplotlib==3.9.2",
     "notebook==7.2.2",
     "nbsphinx==0.9.5",
     "numpydoc==1.8.0",
     "pandas==2.2.3",
     "Pillow>=9.0",
+    "plotly==5.24.1",
     "PyGitHub==2.4.0",
     "pyvista[jupyter]==0.44.1",
     "requests==2.32.3",