docs: Add support for plotly example rendering (#395)

Co-authored-by: pyansys-ci-bot <[email protected]>

Author: AlejandroFernandezLuces

doc/changelog.d/395.miscellaneous.md

@@ -0,0 +1 @@
+Docs: Add support for plotly example rendering

doc/source/conf.py

@@ -11,6 +11,8 @@
     latex,
     watermark,
 )
+import plotly.io as pio
+from plotly.io._sg_scraper import plotly_sg_scraper
 import pyvista
 from pyvista.plotting.utilities.sphinx_gallery import DynamicScraper
 from sphinx.builders.latex import LaTeXBuilder
@@ -20,6 +22,9 @@
 
 ansys.tools.visualization_interface.DOCUMENTATION_BUILD = True
 
+pio.renderers.default = "sphinx_gallery"
+
+
 LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
 
 os.environ["PYANSYS_VISUALIZER_DOC_MODE"] = "true"
@@ -107,7 +112,7 @@
     "backreferences_dir": None,
     # Modules for which function level galleries are created.  In
     "doc_module": "ansys-tools-visualization-interface",
-    "image_scrapers": (DynamicScraper(), "matplotlib"),
+    "image_scrapers": (DynamicScraper(), "matplotlib", plotly_sg_scraper),
     "ignore_pattern": "flycheck*",
     "thumbnail_size": (350, 350),
     "remove_config_comments": True,

doc/source/user_guide/migration.rst

@@ -214,4 +214,36 @@ This topic explains how to migrate from the PyVista documentation configuration
 
 .. code-block:: python
 
-    nbsphinx_execute = "always"
+    nbsphinx_execute = "always"
+
+
+For Plotly, in ``conf.py``, do the following:
+
+1. Add environment variables for documentation:
+
+.. code-block:: python
+
+    os.environ["PYANSYS_VISUALIZER_DOC_MODE"] = "true"
+
+
+2. Add plotly configuration
+
+.. code-block:: python
+
+    import plotly.io as pio
+
+    pio.renderers.default = "sphinx_gallery"
+
+
+3. Import and add scraper
+
+.. code-block:: python
+
+    from plotly.io._sg_scraper import plotly_sg_scraper
+
+    sphinx_gallery_conf = {
+        "image_scrapers": (DynamicScraper(), "matplotlib", plotly_sg_scraper),
+    }
+
+
+4. **[IMPORTANT]** The ``pl.show()`` must be the last line of code in the cell, or else it won't show.

doc/styles/config/vocabularies/ANSYS/accept.txt

@@ -1,6 +1,8 @@
 (?i)Ansys
 pytest
 unhovered
+(?i)Plotly
+
 
 t.M
 a.P

examples/01-basic-plotly-examples/plain-usage.py

@@ -55,14 +55,14 @@
 # Plot the MultiBlock
 pl.plot(multi_block)
 
-#####################
 # Display the plotter
-#
-# code-block:: python
-#
-#   pl.show()
 
+pl.show()
+
+############################
 # Now create a custom object
+# ==========================
+
 class CustomObject:
     def __init__(self):
         self.name = "CustomObject"
@@ -89,12 +89,14 @@ def name(self):
 # Display the plotter again
 # =========================
 # Since Plotly is a web-based visualization, we can show the plot again to include the new object.
-#
-# code-block:: python
-#
-#   pl.show()
 
+pl.show()
+
+
+#####################################
 # Add a Plotly Mesh3d object directly
+# ===================================
+
 custom_mesh3d = Mesh3d(
     x=[0, 1, 2],
     y=[0, 1, 0],
@@ -119,12 +121,4 @@ def name(self):
 )
 pl.plot(scatter)
 
-
-
-###########################
-# Display the plotter again
-# =========================
-#
-# code-block:: python
-#
-#   pl.show()
+pl.show()

src/ansys/tools/visualization_interface/backends/plotly/plotly_interface.py

@@ -186,7 +186,7 @@ def show(self,
             plottable_object=None,
             screenshot: str = None,
             name_filter=None,
-            **kwargs) -> None:
+            **kwargs) -> Union[go.Figure, None]:
         """Render the Plotly scene.
 
         Parameters
@@ -199,11 +199,19 @@ def show(self,
             Flag to filter the object, by default None.
         kwargs : dict
             Additional options the selected backend accepts.
+
+        Returns
+        -------
+        Union[go.Figure, None]
+            The figure of the plot if in doc building environment. Else, None.
         """
+        import os
+        if os.environ.get("PYANSYS_VISUALIZER_DOC_MODE"):
+            return self._fig
+
         if plottable_object is not None:
             self.plot(plottable_object)
 
-
         # Only show in browser if no screenshot is being taken
         if not screenshot:
             self._fig.show(**kwargs)