diff --git a/doc/changelog.d/395.miscellaneous.md b/doc/changelog.d/395.miscellaneous.md new file mode 100644 index 00000000..345b36b9 --- /dev/null +++ b/doc/changelog.d/395.miscellaneous.md @@ -0,0 +1 @@ +Docs: Add support for plotly example rendering diff --git a/doc/source/conf.py b/doc/source/conf.py index 0641e28b..4d50625c 100644 --- a/doc/source/conf.py +++ b/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, diff --git a/doc/source/user_guide/migration.rst b/doc/source/user_guide/migration.rst index d4c5f397..4a670b4c 100644 --- a/doc/source/user_guide/migration.rst +++ b/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" \ No newline at end of file + 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. \ No newline at end of file diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index b6c2a123..c7c74061 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -1,6 +1,8 @@ (?i)Ansys pytest unhovered +(?i)Plotly + t.M a.P diff --git a/examples/01-basic-plotly-examples/plain-usage.py b/examples/01-basic-plotly-examples/plain-usage.py index 94c21950..adf3294a 100644 --- a/examples/01-basic-plotly-examples/plain-usage.py +++ b/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() \ No newline at end of file +pl.show() diff --git a/src/ansys/tools/visualization_interface/backends/plotly/plotly_interface.py b/src/ansys/tools/visualization_interface/backends/plotly/plotly_interface.py index c74b7708..2d098d7a 100644 --- a/src/ansys/tools/visualization_interface/backends/plotly/plotly_interface.py +++ b/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)