Documentation: improvements for the DPF Server getting started section (#675)

* Environment flag replaced by environment variable

* Update customer portal link (support before)

* Fix DPFPreviewLicenseAgreement term

* DPF page of the ansys customer portal

* Update the pydpf-core and post related information in getting_started_with_dpf_server

* Update Ansys Installer install instructions in index of getting_started

* Make the information about the DPF Preview License Agreement clearer

* entry/premium space clearer

* print(entry_server.context)

* Add Install with plotting capabilities section in install and troubleshooting

* Fix ref_compatibility

* Update entry/premium capabilities check/checkout information

* Update troubleshooting

* Update troubleshoot (pyvista sentence)

* Update docs/source/user_guide/troubleshooting.rst

Co-authored-by: PProfizi <[email protected]>

* Update docs/source/getting_started/index.rst

Co-authored-by: PProfizi <[email protected]>

* increments typo

* Replace via by using

* Small fixes after building

* Small fixes

Co-authored-by: PProfizi <[email protected]>

Author: anslpa

ansys/dpf/core/server_context.py

@@ -16,9 +16,11 @@
 
 class LicensingContextType(Enum):
     premium = 1
-    """Allows capabilities requiring Licenses checkout."""
+    """Loads the entry and the premium capabilities that require a license checkout.
+    Blocks an increment."""
     entry = 4
-    """Loads minimum capabilities without requiring any Licenses checkout."""
+    """Loads the minimum number of plugins for basic use. Checks if at least one
+    increment exists. This increment won't be blocked."""
 
     def __int__(self):
         return self.value

docs/source/getting_started/compatibility.rst

@@ -83,6 +83,7 @@ To get a specific version of the ``ansys-dpf-core`` package, such as 0.7.0, use
 
     pip install --force-reinstall ansys-dpf-core==0.7.0
 
+.. _target_environment_variable_with_dpf_section:
 
 Environment variable
 --------------------

docs/source/getting_started/index.rst

@@ -30,12 +30,14 @@ Installing DPF Server
 ---------------------
 
 #. DPF Server is packaged within the **Ansys Unified Installer** starting with Ansys 2021 R1.
-   To use it, install Ansys following the installer instructions. If you experience problems,
-   see  :ref:`Environment variable section <ref_compatibility>`. For information on getting
+   To use it, download the standard installation using your preferred distribution channel, 
+   and install Ansys following the installer instructions. If you experience problems,
+   see  :ref:`Environment variable section <target_environment_variable_with_dpf_section>`. For information on getting
    a licensed copy of Ansys, visit the `Ansys website <https://www.ansys.com/>`_.
 
-#. DPF Server is available as a **standalone** package (independent of the Ansys installer) on the `Ansys Customer Portal <https://support.ansys.com/Home/HomePage>`_.
-   As explained in :ref:`Ansys licensing section <ref_getting_started_with_dpf_server>`,
+#. DPF Server is available as a **standalone** package (independent of the Ansys installer) on the 
+   `DPF page of the Ansys Customer Portal <https://download.ansys.com/>`_.
+   As explained in :ref:`Ansys licensing section <target_to_ansys_license_mechanism>`,
    DPF Server is protected by an Ansys license mechanism. Once you have access to an
    Ansys license, install DPF Server:
 
@@ -52,15 +54,16 @@ Installing DPF Server
         pip install -e .
 
     * DPF Server is protected using the license terms specified in the
-    ``DPFUserLicensingAgreement.txt`` file, which is available on the
+    ``DPFPreviewLicenseAgreement`` file, which is available on the
     Ansys Customer Portal. To accept these terms, you must set the
-    following environment flag:
+    following environment variable:
 
     .. code::
 
         ANSYS_DPF_ACCEPT_LA=Y
 
-
+For more information about the license terms, see the :ref:`DPF Preview License Agreement<target_to_license_terms>` 
+section.
 
 For installation methods that do not use pip, such as using **Docker containers**, see
 :ref:`ref_getting_started_with_dpf_server`.

docs/source/getting_started/install.rst

@@ -54,3 +54,18 @@ clone the repository and install it using ``pip`` with the ``-e``
 development flag:
 
 .. include:: ../pydpf-core_clone_install.rst
+
+
+.. _target_to_install_with_plotting_capabilities:
+
+Install with plotting capabilities
+----------------------------------
+
+PyDPF-Core plotting capabilities are based on PyVista. That means that PyVista must be installed with PyDPF-Core. 
+To proceed, use:
+
+.. code::
+
+   pip install ansys-dpf-core[plotting]
+
+For more information about PyDPF-Core plotting capabilities, see :ref:`ref_plotter`.

docs/source/user_guide/getting_started_with_dpf_server.rst

@@ -31,16 +31,23 @@ Installing DPF Server
 .. code::
 
     pip install -e . 
-	
-PyDPF-Core and PyDPF-Post python modules can now be used. The instructions to install and get started with PyDPF-Core 
-(ansys-dpf-core module) can be found at `Getting Started section <https://dpf.docs.pyansys.com/getting_started/install.html>`_. 
 
 Using DPF Server
 ----------------
 
+DPF Server use is protected using license terms. For more information, see the :ref:`DPF Preview License Agreement<target_to_license_terms>` section.
+
 Running the DPF Server with PyDPF
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+PyDPF-Core is a Python client API communicating with a **DPF Server**, either
+through the network using gRPC or directly in the same process. PyDPF-Post is a Python
+module for postprocessing based on PyDPF-Core. 
+
+Both PyDPF-Core and PyDPF-Post python modules can be used with the DPF Server. The instructions to install and get started with PyDPF-Core 
+can be found at `PyDPF-Core, Getting Started section <https://dpf.docs.pyansys.com/getting_started/install.html>`_. The instructions to install and get
+started with PyDPF-Post can be found at `PyDPF-Post, Getting Started section <https://post.docs.pyansys.com/getting_started/install.html>`_.
+
 With PyDPF-Core and PyDPF-Post, the first creation of most DPF entities will start a DPF Server with the current default configuration and context.
 For example, the following code will automatically start a DPF Server behind the scenes:
 
@@ -71,20 +78,20 @@ Running the DPF Server in a Docker container
 
     docker build . -t dpf-core:v2023_2_pre0 --build-arg DPF_VERSION=232 --build-arg DPF_SERVER_FILE=ansys_dpf_server_lin_v2023.2.pre0.zip
 
-4. To run the DPF Docker container, see the :ref:`License terms<target_to_license_terms>` section.
+4. To run the DPF Docker container, see the :ref:`DPF Preview License Agreement<target_to_license_terms>` section.
 
 License terms
 -------------
 
+.. _target_to_license_terms:
+
 DPF Preview License Agreement 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. _target_to_license_terms:
-
-DPF Server is protected using license terms specified in the DPFPreviewLicenseAgreement file that 
+DPF Server use is protected using license terms specified in the DPFPreviewLicenseAgreement file that 
 can be found on the Ansys Customer Portal.
 
-To accept the DPF User Licensing Agreement terms, the following environment flag must be set: 
+To accept the DPF User Licensing Agreement terms, the following environment variable must be set: 
 
 .. code::
 
@@ -102,26 +109,31 @@ For a DPF Docker container usage, it can be set using:
 For any other case, set "ANSYS_DPF_ACCEPT_LA" as an environment variable with "Y" value.
 
 Replace "<license_server_to_use>" mention that ANSYSLMD_LICENSE_FILE environment variable points to the Ansys license server.
-For more information about Ansys license mechanism use with DPF Server, see :ref:`Ansys licensing section<target_to_ansys_license_mechanism>`.
+For more information about Ansys license mechanism use with DPF Server, see :ref:`Ansys licensing<target_to_ansys_license_mechanism>` section.
 
 
+.. _target_to_ansys_license_mechanism:
+
 Ansys licensing
 ~~~~~~~~~~~~~~~
 
-.. _target_to_ansys_license_mechanism:
-
 DPF Server is protected by Ansys licensing mechanism.
 
-DPF capabilities are available through the following main services: 
-- Entry: Loads the minimum number of plugins for basic use. It is the default. It will only check if an Ansys License is available. 
-- Premium: Loads the entry and the premium capabilities that require a license checkout. 
+DPF capabilities are available through the following main contexts: 
+
+- Entry: Loads the minimum number of plugins for basic use. It is the default. Checks if at least one increment exists 
+  from the following :ref:`Ansys licensing increments list<target_to_ansys_license_increments_list>`. This increment won't be blocked.
+- Premium: Loads the entry and the premium capabilities that require a license checkout. Blocks an increment from the 
+  following :ref:`Ansys licensing increments list<target_to_ansys_license_increments_list>`.
 
 To update the context, apply a new server context:
 
 .. code::
 
     dpf.apply_server_context(dpf.AvailableServerContexts.premium)
 
+.. _target_to_ansys_license_increments_list:
+
 The following Ansys licensing increments currently provide rights to use DPF Server: 
 
 - "preppost" available in Ansys Mechanical Enterprise PrepPost product

docs/source/user_guide/server_context.rst

@@ -39,7 +39,13 @@ This won't check out any license.
 	   
     from ansys.dpf import core as dpf
     entry_server = dpf.start_local_server()
-    entry_server.context
+    print(entry_server.context)
+
+.. rst-class:: sphx-glr-script-out
+
+ .. code-block:: none
+ 
+    Server Context of type LicensingContextType.entry with no xml path
 
 Getting started with Premium capabilities
 -----------------------------------------

docs/source/user_guide/troubleshooting.rst

@@ -34,7 +34,7 @@ Assume that you are importing the ``pydpf-core`` package:
 
     from ansys.dpf import core as dpf
 
-If an error lists missing modules, see :ref:`ref_ref_compatibility`.
+If an error lists missing modules, see :ref:`ref_compatibility`.
 The `ansys.grpc.dpf <https://pypi.org/project/ansys-grpc-dpf/>`_ module
 should always be synchronized with its server version.
 
@@ -66,6 +66,24 @@ Then, with result files reproducing this issue, you can prevent the warning from
 However, the preceding code disables the reading and generation of the available results for the model.
 Any static results that are available for the model are used instead.
 
+Plotting issues
+---------------
+
+When trying to plot a result with DPF, the following error might be raised:
+
+.. code-block:: default
+
+    ModuleNotFoundError: No module named 'pyvista'
+
+In that case, simply install PyVista with:
+
+.. code-block:: default
+
+    pip install pyvista
+
+Another option is to install PyVista along PyDPF-Core. For more information, see 
+:ref:`Install with plotting capabilities<target_to_install_with_plotting_capabilities>`
+
 Performance issues
 ------------------