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,13 @@
 from datetime import datetime
 import os
 from pathlib import Path
-from typing import List
+from typing import Dict, List
 
 from github import Github
+import plotly.io as pio
 import pyvista
 import requests
+from sphinx.application import Sphinx
 from sphinx.builders.latex import LaTeXBuilder
 
 from ansys_sphinx_theme import (
@@ -24,6 +26,8 @@
     watermark,
 )
 
+pio.renderers.default = "sphinx_gallery"
+
 THIS_PATH = Path(__file__).parent.resolve()
 EXAMPLE_PATH = (THIS_PATH / "examples" / "sphinx_examples").resolve()
 
@@ -133,8 +137,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 +184,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 +238,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")
@@ -246,34 +249,39 @@ def download_and_process_files(example_links: List[str]) -> List[str]:
         "package_depth": 1,
     }
 
+    import plotly.io as pio
+    from plotly.io._sg_scraper import plotly_sg_scraper
+
+    pio.renderers.default = "sphinx_gallery"
+
     # 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"],
         # 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"),
+        "image_scrapers": ("pyvista", "matplotlib", plotly_sg_scraper),
         "default_thumb_file": "source/_static/pyansys_light_square.png",
+        "capture_repr": ("_repr_html_", "__repr__"),
     }
+    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 +300,15 @@ 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."""
+    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,42 @@
 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 Matplotlib.
+
+import plotly
+import plotly.graph_objs as go
+
+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])
+plotly.io.show(fig)
+
 ###############################################################################
 # Render equations using IPython ``math``
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -80,18 +116,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 +152,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",