Adding dynamic plots in documentation

doc/source/conf.py

@@ -11,6 +11,7 @@
 )
 import numpy as np
 import pyvista
+from pyvista.plotting.utilities.sphinx_gallery import DynamicScraper
 from sphinx.application import Sphinx
 from sphinx_gallery.sorting import FileNameSortKey
 
@@ -21,22 +22,18 @@
 pyvista.set_error_output_file("errors.txt")
 
 # Ensure that offscreen rendering is used for docs generation
+pyvista.BUILDING_GALLERY = True
 pyvista.OFF_SCREEN = True
 
 # must be less than or equal to the XVFB window size
-try:
-    pyvista.global_theme.window_size = np.array([1024, 768])
-except AttributeError:
-    # for compatibility with pyvista < 0.40
-    pyvista.rcParams["window_size"] = np.array([1024, 768])
+pyvista.global_theme.window_size = np.array([1024, 768])
 
 # Save figures in specified directory
 pyvista.FIGURE_PATH = os.path.join(os.path.abspath("./images/"), "auto-generated/")
 if not os.path.exists(pyvista.FIGURE_PATH):
     os.makedirs(pyvista.FIGURE_PATH)
 
 # necessary when building the sphinx gallery
-pyvista.BUILDING_GALLERY = True
 pymapdl.BUILDING_GALLERY = True
 
 # suppress annoying matplotlib bug
@@ -73,6 +70,7 @@
 extensions = [
     "jupyter_sphinx",
     "numpydoc",
+    "pyvista.ext.viewer_directive",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.coverage",
@@ -238,7 +236,7 @@
     "backreferences_dir": None,
     # Modules for which function level galleries are created.  In
     "doc_module": "ansys-mapdl-core",
-    "image_scrapers": ("pyvista", "matplotlib"),
+    "image_scrapers": (DynamicScraper(), "matplotlib"),
     "ignore_pattern": "flycheck*",
     "thumbnail_size": (350, 350),
     "remove_config_comments": True,

doc/source/getting_started/running_mapdl.rst

@@ -136,9 +136,10 @@ Note that you must have started MAPDL in gRPC mode on the computer with
 the mentioned IP address/hostname for this to work.
 
 If you have MAPDL installed on your local host, you
-can use the :func:`launch_mapdl() <ansys.mapdl.core.launch_mapdl>` method to both start and connect to MAPDL.
+can use the :func:`launch_mapdl() <ansys.mapdl.core.launch_mapdl>` method to both start and
+connect to MAPDL.
 
-If you have any problem launching PyMAPDL, see :ref:`debugging_launch_mapdl`.
+If you have any problem launching PyMAPDL, see :ref:`Launching issues <ref_launching_issue>`.
 
 If you are connecting to an MAPDL Docker image, the procedure is the same.
 Just make sure that you specify the mapped port instead of the internal Docker image port.

doc/source/user_guide/index.rst

@@ -222,4 +222,4 @@ with it. For example:
         recommended.
 
 
-For stability considerations, see :ref:`ref_pymapdl_stability`.
+For stability considerations, see :ref:`PyMAPDL stability <ref_pymapdl_stability>`.

doc/source/user_guide/parameters.rst

@@ -46,7 +46,8 @@ ROUT``, you can access it with this code:
 For a full list of the methods and attributes available to the
 ``Parameters`` class, see :ref:`ref_parameters_api`.
 
-For additional information on PyMAPDL array limitations, see :ref:`ref_numpy_arrays_in_mapdl`.
+For additional information on PyMAPDL array limitations, see
+:ref:`Issues when importing and exporting numpy arrays in MAPDL <ref_issues_np_mapdl>`.
 
 .. _ref_special_named_param:
 

doc/source/user_guide/troubleshoot.rst

@@ -1,10 +1,6 @@
-
-
-
 .. _ref_troubleshooting:
 
 
-=======================
 Troubleshooting PyMAPDL
 =======================
 
@@ -13,9 +9,8 @@ To help you resolve any problems that you might have when using PyMAPDL,
 some of the most common problems and frequently asked questions are posted here.
 
 
-*****************
 Debug in PyMAPDL
-*****************
+----------------
 
 If you are having trouble with PyMAPDL, you can record some internal
 logs into a file using a logger. 
@@ -43,11 +38,10 @@ If you believe you have found a bug, open an issue on the
 `PyMAPDL Issues page <pymapdl_issues_>`_.
 
 
-.. _debugging_launch_mapdl:
+.. _ref_launching_issue:
 
-****************
 Launching issues
-****************
+----------------
 
 There are several issues that can cause MAPDL not to launch, including:
 
@@ -63,7 +57,7 @@ There are several issues that can cause MAPDL not to launch, including:
 
 
 Connection timeout
-==================
+~~~~~~~~~~~~~~~~~~
 
 In some networks, MAPDL might take longer than expected to connect to the license server or to the remote instance.
 In those cases, you might see the following message:
@@ -93,12 +87,11 @@ Or if you are connecting to a remote instance you can use:
 
 
 Testing MAPDL launching
-=======================
+~~~~~~~~~~~~~~~~~~~~~~~
 
 In some cases, it may be necessary to run the launch command manually from the command line.
 
-On Windows
-----------
+**On Windows**
 
 Open up a command prompt and run the version-dependent command:
 
@@ -109,8 +102,7 @@ Open up a command prompt and run the version-dependent command:
 .. note:: PowerShell users can run the preceding command without quotes.
 
 
-On Linux
---------
+**On Linux**
 
 Run the version-dependent command:
 
@@ -153,7 +145,7 @@ If this command doesn't launch MAPDL, look at the command output:
 .. vale on
 
 Licensing issues
-================
+~~~~~~~~~~~~~~~~
 
 Incorrect license server configuration can prevent MAPDL from being able to get a valid license.
 In such cases, you might see output **similar** to:
@@ -184,7 +176,7 @@ for maintaining Ansys licensing or have a personal install of Ansys, see the onl
 For more comprehensive information, download the :download:`ANSYS Licensing Guide <lic_guide.pdf>`.
 
 Incorrect licensing environment variables
------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The license server can be also specified using the environment variable :envvar:`ANSYSLMD_LICENSE_FILE`.
 The following code examples show how you can see the value of this environment variable on
@@ -209,7 +201,7 @@ either Windows or Linux.
 .. _vpn_issues_troubleshooting:
 
 Virtual private network (VPN) issues
-====================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 From ANSYS 2022 R2 to ANSYS 2021 R1, MAPDL has issues launching when VPN software is running.
 One issue stems from MPI communication and can be solved by either passing
@@ -248,18 +240,14 @@ On Windows, you can find the license configuration file that points to the licen
 .. _missing_dependencies_on_linux:
 
 Missing dependencies on Linux
-=============================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Some Linux installations might be missing required dependencies. If
 you get errors like ``libXp.so.6: cannot open shared object file: No
 such file or directory``, you are likely missing some necessary
 dependencies.
 
-
-.. _installing_mapdl_on_centos7:
-
-CentOS 7
---------
+**CentOS 7**
 
 On CentOS 7, you can install missing dependencies with:
 
@@ -268,10 +256,7 @@ On CentOS 7, you can install missing dependencies with:
     yum install openssl openssh-clients mesa-libGL mesa-libGLU motif libgfortran
 
 
-.. _installing_mapdl_on_ubuntu:
-
-Ubuntu
-------
+**Ubuntu**
 
 On Ubuntu 22.04, use this code to install the needed dependencies:
 
@@ -300,8 +285,8 @@ using this code:
     apt-get install -y libxp6
 
 
-Ubuntu 20.04 and older
-----------------------
+
+**Ubuntu 20.04 and older**
 
 If you are using Ubuntu 16.04, you can install ``libxp16`` with this code:
 
@@ -333,7 +318,7 @@ then installs it via the ``dpkg`` package.
 .. _conflicts_student_version:
 
 Conflicts with student version
-==============================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Although you can install Ansys together with other Ansys products or versions, on Windows, you
 should not install a student version of an Ansys product together with its non-student version.
@@ -353,7 +338,8 @@ to the correct location.
    ``SMP`` mode, unless another MPI option is specified.
 
 Incorrect environment variables
-===============================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 If you are using a non-standard install, you might need to manually set the
 environment variables ``ANSYSXXX_DIR``, ``AWP_ROOTXXX``, and
 ``CADOE_LIBDIRXXX`` to the correct location. 
@@ -387,7 +373,8 @@ shown. For Ansys MAPDL 2022 R2, ``222`` appears where ``XXX`` is shown.
 .. vale on
 
 Using a proxy server
-====================
+~~~~~~~~~~~~~~~~~~~~
+
 In some rare cases, you might experience some problems to connect to the MAPDL instance if you are
 using a proxy.
 When `gRPC <grpc_>`_ is used in a proxy environment, if a local address is specified (that is ``127.0.0.1``)
@@ -399,7 +386,8 @@ to connect to MAPDL instance.
 
 
 Firewall settings
-=================
+~~~~~~~~~~~~~~~~~
+
 MAPDL and Python should have the correct firewall settings to allow communication between the two.
 If you are using a firewall, you should allow MAPDL to receive inbound connections to the following ports:
 
@@ -425,8 +413,12 @@ For more information on how to **configure your firewall on Ubuntu Linux**, plea
 link `Security-Firewall | Ubuntu <ubuntu_firewall_>`_.
 
 
+Location of the executable file
+-------------------------------
+
 Manually set the location of the executable file
-================================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 If you have a non-standard install, PyMAPDL might be unable find
 your MAPDL installation. If this is the case, provide the location of MAPDL
 as the first parameter to :func:`launch_mapdl() <ansys.mapdl.core.launch_mapdl>`.
@@ -450,7 +442,7 @@ as the first parameter to :func:`launch_mapdl() <ansys.mapdl.core.launch_mapdl>`
 
 
 Default location of the executable file
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The first time that you run PyMAPDL, it detects the
 available Ansys installations.
@@ -520,20 +512,18 @@ method lists higher versions first and student versions last.
     information, see :ref:`conflicts_student_version`.
 
 
-.. _ref_pymapdl_limitations:
 
-*********************
 PyMAPDL usage issues
-*********************
+--------------------
 
-.. _ref_numpy_arrays_in_mapdl:
+.. _ref_issues_np_mapdl:
 
-Issues when importing and exporting numpy arrays in MAPDL
-=========================================================
+Issues when importing and exporting NumPy arrays in MAPDL
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Because of the way MAPDL is designed, there is no way to store an
 array where one or more dimensions are zero.
-This can happens in numpy arrays, where its first dimension can be
+This can happens in NumPy arrays, where its first dimension can be
 set to zero. For example:
 
 .. code:: pycon
@@ -583,22 +573,20 @@ to one, have the same shape if later retrieved.
    True
 
 
-
 .. _ref_pymapdl_stability:
 
-*****************
 PyMAPDL stability
-*****************
+-----------------
 
 Recommendations
-===============
+~~~~~~~~~~~~~~~
 
 When connecting to an instance of MAPDL using gRPC (default), there are some cases
 where the MAPDL server might exit unexpectedly. There
 are several ways to improve MADPL performance and stability:
 
 Use ``mute`` to improve stability
------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When possible, pass ``mute=True`` to individual MAPDL commands or
 set it globally with the :func:`Mapdl.mute
@@ -610,14 +598,16 @@ verbosity as needed.
 
 
 Issues
-======
+~~~~~~
 
 .. note::
+
    MAPDL 2021 R1 has a stability issue with the :func:`Mapdl.input()
    <ansys.mapdl.core.Mapdl.input>` method. Avoid using input files if
-   possible. Attempt to use the :func:`Mapdl.upload()
-   <ansys.mapdl.core.Mapdl.upload>` method to upload nodes and elements and read them
-   in via the :func:`Mapdl.nread() <ansys.mapdl.core.Mapdl.nread>` and
+   possible. Attempt to use the
+   :func:`Mapdl.upload() <ansys.mapdl.core.Mapdl.upload>` method to upload
+   nodes and elements and read them in via the
+   :func:`Mapdl.nread() <ansys.mapdl.core.Mapdl.nread>` and
    :func:`Mapdl.eread() <ansys.mapdl.core.Mapdl.eread>` methods.
 
 

pyproject.toml

@@ -89,15 +89,18 @@ doc = [
     "pypandoc==1.11",
     "pytest-sphinx==0.5.0",
     "pythreejs==2.4.2",
-    "pyvista[trame]==0.42.3",
+    "pyvista[jupyter,trame]==0.42.3",
     "sphinx-autobuild==2021.3.14",
     "sphinx-autodoc-typehints==1.24.0",
     "sphinx-copybutton==0.5.2",
     "sphinx-gallery==0.14.0",
     "sphinxcontrib-websupport==1.2.6",
     "sphinxemoji==0.2.0",
     "sphinx-reredirects==0.1.2",
+    "trame==3.2.6",
     "vtk==9.2.6",
+    "sphinx-toolbox",
+    "sphinxcontrib-websupport",
 ]
 
 [tool.flit.module]