doc: Add extended migration guide (#363)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Kathy Pippert <[email protected]>

Author: 4 people

doc/changelog.d/363.miscellaneous.md

@@ -0,0 +1 @@
+Doc: Add extended migration guide

doc/source/index.rst

@@ -68,6 +68,7 @@ The Visualization Interface Tool offers these main features:
 
        getting_started/index
        user_guide/index
+       user_guide/migration
        {% if build_api %}
        api/index
        {% endif %}

doc/source/user_guide/index.rst

@@ -6,7 +6,8 @@ User guide
 
 This section explains key concepts for implementing the Visualization Interface Tool in your workflow.
 You can use the Visualization Interface Tool in your examples as well as integrate this library into
-your own code.
+your own code. For information on how to migrate from PyVista to the Ansys Visualization Interface Tool, see
+:ref:`ref_migration_guide`.
 
 Default plotter usage
 =====================
@@ -45,7 +46,7 @@ Use with PyAnsys custom objects
 
 You can also use the default plotter to visualize PyAnsys custom objects. The only requirement is that the
 custom object must have a method that returns a PyVista mesh a method that exposes a ``name`` or
-``id`` attribute of your object. To expose a custom object, you use a ``MeshObjectPlot`` instance. This class
+``id`` attribute of your object. To expose a custom object, you use a :class:`~ansys.tools.visualization_interface.types.mesh_object_plot.MeshObjectPlot` instance. This class
 relates PyVista meshes with any object.
 
 The following code shows how to use the default plotter to visualize a PyAnsys custom object:
@@ -99,7 +100,7 @@ class. After that, see these main use cases for customizing the plotter:
 * The most common use case is to customize the way that the objects you represent are shown in the plotter.
   To this end, you can override the ``plot`` and ``plot_iter`` methods. These methods are called every time
   a new object is added to the plotter. The default implementation of this method is to add a PyVista mesh
-  or a  ``MeshObjectPlot`` instance to the plotter. You can override this method to add your own meshes or
+  or a :class:`~ansys.tools.visualization_interface.types.mesh_object_plot.MeshObjectPlot` instance to the plotter. You can override this method to add your own meshes or
   objects to the plotter in a manner that fits the way that you want to represent the meshes.
 
 * Another use case is the need to have custom button functionalities for your library. For example, you may
@@ -109,15 +110,17 @@ class. After that, see these main use cases for customizing the plotter:
 Some practical examples of how to use the ``PlotterInterface`` class are included in some PyAnsys libraries,
 such as `PyAnsys Geometry <https://github.com/ansys/pyansys-geometry/pull/959>`_.
 
+For comprehensive migration information with code examples, see :ref:`ref_migration_guide`.
+
 
 Customizing the picker and hover callbacks
 ==========================================
 
-The Visualization Interface Tool provides a base class, ``AbstractPicker``, for customizing the picker and hover
+The Visualization Interface Tool provides a base class, :class:`~ansys.tools.visualization_interface.backends.pyvista.picker.AbstractPicker`, for customizing the picker and hover
 callbacks of the plotter. This class provides a set of methods that can be overridden so that you can adapt the
 picker and hover functionalities to the specific need of your PyAnsys library.
 
-The first thing you must do is to create a class that inherits from the ``AbstractPicker`` class. After that, see
+The first thing you must do is to create a class that inherits from the :class:`~ansys.tools.visualization_interface.backends.pyvista.picker.AbstractPicker` class. After that, see
 these main use cases for customizing the picker and hover callbacks:
 
 * You may want to change the way that objects are picked in the plotter. To do this, you can override the
@@ -128,4 +131,4 @@ these main use cases for customizing the picker and hover callbacks:
   override the ``hover_select_object`` and ``hover_unselect_object`` methods. These methods are called when an
   object is hovered over or unhovered, respectively.
 
-A practical example of how to use the ``AbstractPicker`` class are included in the examples section of the documentation.
+A practical example of how to use the :class:`~ansys.tools.visualization_interface.backends.pyvista.picker.AbstractPicker` class is included in :ref:`sphx_glr_examples_00-basic-pyvista-examples_custom_picker.py`.

doc/source/user_guide/migration.rst

@@ -0,0 +1,217 @@
+.. _ref_migration_guide:
+
+Migration
+#########
+
+This section helps you migrate from PyVista plotters to the Ansys Tools Visualization Interface plotters.
+It consists of two major topics:
+
+- `Code migration`_
+- `Documentation configuration migration`_
+
+Code migration
+==============
+This topic explains how to migrate from PyVista plotters to the new Ansys Tools Visualization Interface plotters. Because cases vary greatly, it provides a few examples that cover the most common scenarios.
+
+Replace PyVista plotter code with Ansys Tools Visualization Interface plotter code
+----------------------------------------------------------------------------------
+If you only need to plot simple PyVista meshes, you can directly replace your PyVista plotter code with the Ansys Tools Visualization Interface plotter code.
+On top of common PyVista functionalities, the Ansys Tools Visualization Interface plotter provides additional interactivity such as view buttons and mesh slicing.
+
+The following code shows how to do the plotter code replacement:
+
+- PyVista code:
+
+.. code-block:: python
+
+    import pyvista as pv
+
+    # Create a PyVista mesh
+    mesh = pv.Cube()
+
+    # Create a plotter
+    pl = pv.Plotter()
+
+    # Add the mesh to the plotter
+    pl.add_mesh(mesh)
+
+    # Show the plotter
+    pl.show()
+
+- Ansys Tools Visualization Interface code:
+
+.. code-block:: python
+
+    import pyvista as pv
+    from ansys.tools.visualization_interface import Plotter
+
+    # Create a PyVista mesh
+    mesh = pv.Cube()
+
+    # Create a plotter
+    pl = Plotter()
+
+    # Add the mesh to the plotter
+    pl.plot(mesh)
+
+    # Show the plotter
+    pl.show()
+
+
+Convert your custom meshes to objects usable by the Ansys Tools Visualization Interface plotter
+-----------------------------------------------------------------------------------------------
+
+Your custom object must have a method that returns a PyVista mesh and a method that exposes a ``name`` or ``id`` attribute of your object:
+
+.. code-block:: python
+
+    class CustomObject:
+        def __init__(self):
+            self.name = "CustomObject"
+            self.mesh = pv.Cube(center=(1, 1, 0))
+
+        def get_mesh(self):
+            return self.mesh
+
+        def name(self):
+            return self.name
+
+
+You then need to create a :class:`~ansys.tools.visualization_interface.types.mesh_object_plot.MeshObjectPlot` instance that relates the PyVista mesh with your custom object:
+
+.. code-block:: python
+
+    from ansys.tools.visualization_interface import MeshObjectPlot
+
+    custom_object = CustomObject()
+    mesh_object_plot = MeshObjectPlot(
+        custom_object=custom_object,
+        mesh=custom_object.get_mesh(),
+    )
+
+With this, you can use the Ansys Tools Visualization Interface plotter to visualize your custom object. It enables interactivity such as picking and hovering.
+
+
+Customize the PyVista backend
+-----------------------------
+
+You can customize the backend of the Ansys Tools Visualization Interface plotter to enable or turn off certain functionalities. The following code shows how to enable picking:
+
+.. code-block:: python
+
+    from ansys.tools.visualization_interface import Plotter
+    from ansys.tools.visualization_interface.backends import PyVistaBackend
+
+    backend = PyVistaBackend(allow_picking=True)
+
+    # Create a plotter
+    pl = Plotter(backend=backend)
+
+    # Add the MeshObjectPlot instance to the plotter
+    pl.plot(mesh_object_plot)
+
+    # Show the plotter
+    pl.show()
+
+If you want to customize the backend even more, you can create your own backend by inheriting from the :class:`~ansys.tools.visualization_interface.backends.pyvista.PyVistaBackendInterface` class
+and implementing the required methods:
+
+.. code-block:: python
+
+    @abstractmethod
+    def plot_iter(self, plottable_object: Any, name_filter: str = None, **plotting_options):
+        """Plot one or more compatible objects to the plotter.
+
+        Parameters
+        ----------
+        plottable_object : Any
+            One or more objects plot.
+        name_filter : str, default: None.
+            Regular expression with the desired name or names to include in the plotter.
+        **plotting_options : dict, default: None
+            Keyword arguments. For allowable keyword arguments, see the
+            :meth:`Plotter.add_mesh <pyvista.Plotter.add_mesh>` method.
+
+        """
+        pass
+
+
+    @abstractmethod
+    def plot(self, plottable_object: Any, name_filter: str = None, **plotting_options):
+        """Plot a single object to the plotter.
+
+        Parameters
+        ----------
+        plottable_object : Any
+            Object to plot.
+        name_filter : str
+            Regular expression with the desired name or names to include in the plotter.
+        **plotting_options : dict, default: None
+            Keyword arguments. For allowable keyword arguments, see the
+            :meth:`Plotter.add_mesh <pyvista.Plotter.add_mesh>` method.
+
+        """
+        pass
+
+
+The rest of the methods are implemented for you. This ensures that while you can customize what you need for plotting,
+the rest of the functionalities still work as expected. For more information, see the backend documentation. If you
+need to even go further, you can create your own plotter by inheriting from the :class:`~ansys.tools.visualization_interface.backends._base.BaseBackend` class and implementing the required methods,
+although this may break existing features.
+
+Customize the picker or hover behavior
+--------------------------------------
+You can customize the picker of the Ansys Tools Visualization Interface plotter to decide what happens when you pick or hover over an object.
+For example, if you want to print the name of the picked object, you can do it as described in the :ref:`sphx_glr_examples_00-basic-pyvista-examples_custom_picker.py` example.
+
+Use the PyVista Qt backend
+--------------------------
+You can use the PyVista Qt backend with the Ansys Tools Visualization Interface plotter. To do this, you must set the PyVista backend to Qt
+before creating the plotter:
+
+.. code-block:: python
+
+   cube = pv.Cube()
+   pv_backend = PyVistaBackend(use_qt=True, show_qt=True)
+   pl = Plotter(backend=pv_backend)
+   pl.plot(cube)
+   pl.backend.enable_widgets()
+   pv_backend.scene.show()
+
+You can then integrate the plotter into a PyQt or PySide app by disabling the ``show_qt`` parameter.
+For more information about this, see the `PyVista documentation <https://qtdocs.pyvista.org/>`_.
+
+
+Documentation configuration migration
+=====================================
+
+This topic explains how to migrate from the PyVista documentation configuration to the new Ansys Tools Visualization Interface documentation configuration.
+
+1. Add environment variables for documentation:
+
+.. code-block:: python
+
+    os.environ["PYANSYS_VISUALIZER_DOC_MODE"] = "true"
+    os.environ["PYANSYS_VISUALIZER_HTML_BACKEND"] = "true"
+
+2. Use PyVista DynamicScraper:
+
+.. code-block:: python
+
+    from pyvista.plotting.utilities.sphinx_gallery import DynamicScraper
+
+    sphinx_gallery_conf = {
+        "image_scrapers": (DynamicScraper()),
+    }
+
+3. Add PyVista viewer directive to extensions:
+
+.. code-block:: python
+
+    extensions = ["pyvista.ext.viewer_directive"]
+
+4. Make sure you are executing the notebook cells:
+
+.. code-block:: python
+
+    nbsphinx_execute = "always"

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

@@ -1,3 +1,8 @@
 (?i)Ansys
 pytest
-unhovered
+unhovered
+
+t.M
+a.P
+e.B
+r.A

examples/01-advanced-pyansys-examples/mixing_elbow.vtk

@@ -509,7 +509,7 @@ def plot_iter(self, plottable_object: Any, name_filter: str = None, **plotting_o
         plottable_object : Any
             One or more objects to add.
         name_filter : str, default: None.
-            Regular expression with the desired name or names  to include in the plotter.
+            Regular expression with the desired name or names to include in the plotter.
         **plotting_options : dict, default: None
             Keyword arguments. For allowable keyword arguments, see the
             :meth:`Plotter.add_mesh <pyvista.Plotter.add_mesh>` method.
@@ -524,7 +524,7 @@ def plot(self, plottable_object: Any, name_filter: str = None, **plotting_option
         Parameters
         ----------
         plottable_object : Any
-            Object to add.
+            Object to plot.
         name_filter : str
             Regular expression with the desired name or names to include in the plotter.
         **plotting_options : dict, default: None
@@ -618,7 +618,7 @@ def plot(self, plottable_object: Any, name_filter: str = None, **plotting_option
         Parameters
         ----------
         plottable_object : Any
-            Object to add.
+            Object to plot.
         name_filter : str
             Regular expression with the desired name or names to include in the plotter.
         **plotting_options : dict, default: None