feat: enable matplotlib and plotly in examples (#567)

Co-authored-by: Revathyvenugopal162 <[email protected]>
Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Revathy Venugopal <[email protected]>
Co-authored-by: Maxime Rey <[email protected]>

Author: 4 people

.pre-commit-config.yaml

@@ -11,6 +11,7 @@ repos:
   rev: v2.3.0
   hooks:
   - id: codespell
+    exclude: doc/source/examples/nbsphinx/jupyter-notebook.ipynb
     args: ["--ignore-words", "doc/styles/config/vocabularies/ANSYS/accept.txt", "-w"]
 
 - repo: https://github.com/pycontribs/mirrors-prettier

doc/changelog.d/567.added.md

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

doc/source/conf.py

@@ -4,11 +4,13 @@
 import os
 from pathlib import Path
 import subprocess
-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 (
@@ -25,6 +27,7 @@
     watermark,
 )
 
+pio.renderers.default = "sphinx_gallery"
 THIS_PATH = Path(__file__).parent.resolve()
 PYANSYS_LIGHT_SQUARE = (THIS_PATH / "_static" / "pyansys_light_square.png").resolve()
 EXAMPLE_PATH = (THIS_PATH / "examples" / "sphinx_examples").resolve()
@@ -75,6 +78,9 @@
     },
 }
 
+html_js_files = ["https://cdn.plot.ly/plotly-3.0.1.min.js"]
+
+
 index_patterns = {
     "examples/api/": ALL_NODES,
     "examples/sphinx_examples/": TITLES + PARAGRAPHS,
@@ -140,8 +146,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:
@@ -245,8 +251,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")
@@ -262,30 +266,29 @@ def download_and_process_files(example_links: List[str]) -> List[str]:
     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"),
+        "image_scrapers": ("pyvista", "matplotlib", "plotly.io._sg_scraper.plotly_sg_scraper"),
         "default_thumb_file": str(PYANSYS_LIGHT_SQUARE),
     }
+    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",
@@ -309,3 +312,30 @@ def download_and_process_files(example_links: List[str]) -> List[str]:
 jinja_globals = {
     "ANSYS_SPHINX_THEME_VERSION": version,
 }
+
+
+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/nbsphinx/jupyter-notebook.ipynb

@@ -62,6 +62,61 @@
 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
+###############################################################################
+
+import numpy as np
+import plotly.express as px
+
+df = px.data.tips()
+fig = px.bar(
+    df,
+    x="sex",
+    y="total_bill",
+    facet_col="day",
+    color="smoker",
+    barmode="group",
+    template="presentation+plotly",
+)
+fig.update_layout(height=400)
+fig
+
 ###############################################################################
 # Render equations using IPython ``math``
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -80,18 +135,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 +171,5 @@
 df.head()
 
 ###############################################################################
+
+# %%

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

@@ -51,6 +51,7 @@ doc = [
     "numpydoc==1.8.0",
     "pandas==2.2.3",
     "Pillow>=9.0",
+    "plotly==6.0.1",
     "PyGitHub==2.6.1",
     "pyvista[jupyter]==0.44.2",
     "PyYAML==6.0.2",

pyproject.toml

@@ -107,11 +107,14 @@ def sphinx_linkcode_resolve(
     if domain != "py":
         return None
 
-    modname = info["module"]
-    fullname = info["fullname"]
+    modname = info.get("module")
+    fullname = info.get("fullname")
 
-    # Little clean up to avoid library.library
-    if fullname.startswith(modname):
+    if not modname or not fullname:
+        return None
+
+    # Cleanup to avoid redundant prefixes like library.library
+    if fullname.startswith(modname + "."):
         fullname = fullname[len(modname) + 1 :]
 
     submod = sys.modules.get(modname)
@@ -122,49 +125,64 @@ def sphinx_linkcode_resolve(
     for part in fullname.split("."):
         try:
             obj = getattr(obj, part)
-        except Exception:
+        except AttributeError:
             return None
 
-    # Deal with our decorators properly
+    # Handle property decorators properly
     while hasattr(obj, "fget"):
         obj = obj.fget
 
+    # Get the source file path
     try:
         fn = inspect.getsourcefile(obj)
-    except Exception:  # pragma: no cover
+    except Exception:
         fn = None
 
-    if not fn:  # pragma: no cover
+    if not fn:
         try:
             fn = inspect.getsourcefile(sys.modules[obj.__module__])
         except Exception:
             return None
-        return None
 
-    fn = Path(fn).resolve().relative_to(Path(__file__).resolve().parent)
-    fn_components = fn.parts
+    fn = Path(fn).resolve()
+
+    # Ensure fn is within the expected repository directory
+    base_path = Path(__file__).resolve().parent
+    if not fn.is_relative_to(base_path):
+        return None  # Avoid errors due to files outside the expected path
+
+    try:
+        fn = fn.relative_to(base_path)
+    except ValueError:
+        return None  # Avoid errors when the file is not within the base path
+
+    fn_components = list(fn.parts)
 
     if not source_path:
         module = modname.split(".")[0]
-        repo_index = fn_components.index(module)
+        if module in fn_components:
+            repo_index = fn_components.index(module)
+        else:
+            return None  # Module name should be in the path
     else:
         if source_path in fn_components:
             repo_index = fn_components.index(source_path)
         else:
             module = modname.split(".")[0]
-            repo_index = fn_components.index(module)
-            fn_components.insert(repo_index, source_path)
+            if module in fn_components:
+                repo_index = fn_components.index(module)
+                fn_components.insert(repo_index, source_path)
+            else:
+                return None  # Ensure we don't insert at an invalid index
+
     fn = "/".join(fn_components[repo_index:])
 
     try:
         source, lineno = inspect.getsourcelines(obj)
-    except Exception:  # pragma: no cover
+    except Exception:
         lineno = None
 
-    if lineno and not edit:
-        linespec = f"#L{lineno}-L{lineno + len(source) - 1}"
-    else:
-        linespec = ""
+    linespec = f"#L{lineno}-L{lineno + len(source) - 1}" if lineno and not edit else ""
 
     blob_or_edit = "edit" if edit else "blob"
     return f"http://github.com/{library}/{blob_or_edit}/{github_version}/{fn}{linespec}"