Refactor Getting Started and add Licensing

doc/source/concepts/waysofusing.rst

@@ -32,7 +32,7 @@ These capabilities can be accessed through client APIs, as shown here:
 .. image:: ../images/drawings/apis_2.png
 
 
-1. DPF server application can be accessed using Ansys Inc product, or DPF Server package (see :ref:`ref_getting_started_with_dpf_server`) available on the Customer portal.
+1. DPF server application can be accessed using Ansys Inc product, or DPF Server package (see :ref:`ref_dpf_server`) available on the Customer portal.
 
 2. Several client APIs are available (CPython, IronPython, C++, and so on).
 

doc/source/conf.py

@@ -319,7 +319,8 @@ def verify_meilisearch_is_active(app):
     MEILISEARCH_PUBLIC_API_KEY = os.getenv("MEILISEARCH_PUBLIC_API_KEY", None)
     if not MEILISEARCH_PUBLIC_API_KEY:
         sys.stderr.write("Could not find MEILISEARCH_PUBLIC_API_KEY")
-        sys.exit(1)
+        # sys.exit(1)
+
 
 def setup(app):
     app.connect("builder-inited", verify_meilisearch_is_active)

doc/source/getting_started/compatibility.rst

@@ -13,7 +13,7 @@ more information, see `Ansys Platform Support <https://www.ansys.com/solutions/s
 Client-server
 -------------
 
-The DPF server version depends on your installed Ansys version.
+The DPF server version depends on your installed Ansys version or your installed standalone DPF Server pre-release version.
 The following table shows client-server compatibility for supported
 Ansys versions. With Ansys 2022 R2 and later, you can use PyDPF-Core ``0.10`` and later.
 With Ansys 2021 R2 and 2022 R1, you can use PyDPF-Core
@@ -48,6 +48,16 @@ package should also be synchronized with the server version.
      - ``ansys.grpc.dpf`` Python module version
      - ``ansys.dpf.gatebin`` binaries Python module version
      - ``ansys.dpf.gate`` Python module version
+   * - 8.0 (Ansys 2024 R2 pre0)
+     - 0.11.0 and later
+     - None
+     - None
+     - None
+   * - 7.1 (Ansys 2024 R1)
+     - 0.10.1 and later
+     - None
+     - None
+     - None
    * - 7.0 (Ansys 2024 R1 pre0)
      - | 0.10.0 and later
        | 0.9.0
@@ -135,15 +145,3 @@ To get a specific version of the ``ansys-dpf-core`` package, such as 0.7.0, use
 .. code::
 
     pip install --force-reinstall ansys-dpf-core==0.7.0
-
-.. _target_environment_variable_with_dpf_section:
-
-Environment variable
---------------------
-
-The ``start_local_server()``  method uses the ``Ans.Dpf.Grpc.bat`` file or
-``Ans.Dpf.Grpc.sh`` file to start the server. Ensure that the ``AWP_ROOT{VER}``
-environment variable is set to your installed Ansys version. For example, if Ansys
-2022 R2 is installed, ensure that the ``AWP_ROOT222`` environment
-variable is set to the path for this Ansys installation.
-

doc/source/getting_started/dpf_server.rst

@@ -0,0 +1,123 @@
+.. _ref_dpf_server:
+
+==========
+DPF Server
+==========
+
+DPF provides numerical simulation users and engineers with a toolbox for accessing and transforming 
+simulation data. With DPF, you can perform complex preprocessing or postprocessing of large amounts of simulation data within a 
+simulation workflow.
+
+The DPF Server is packaged within the **Ansys installer** in Ansys 2021 R1 and later.
+
+It is also available as a standalone package that contains all the necessary files to run, enabling DPF capabilities.
+The standalone DPF Server is available on the `DPF Pre-Release page <https://download.ansys.com/Others/DPF%20Pre-Release>`_ of the Ansys Customer Portal.
+The first standalone version of DPF Server available is 6.0 (2023 R2).
+
+The sections on this page describe how to install and use a standalone DPF Server.
+
+* For a quick start on using PyDPF, see :ref:`ref_getting_started`.
+* For more information on DPF and its use, see :ref:`ref_user_guide`.
+
+
+Install DPF Server
+------------------
+
+.. _target_installing_server:
+
+#. Download the ``ansys_dpf_server_win_v2024.2.pre0.zip`` or ``ansys_dpf_server_lin_v2024.2.pre0.zip`` file as appropriate.
+#. Unzip the package.
+#. Optional: download any other plugin ZIP file as appropriate and unzip the package. For example, to access the ``composites`` plugin for Linux, 
+   download ``ansys_dpf_composites_lin_v2024.2.pre0.zip`` and unzip the package in the same location as ``ansys_dpf_server_lin_v2024.2.pre0.zip``.
+#. Change to the root folder (``ansys_dpf_server_win_v2024.2.pre0``) of the unzipped package.
+#. In a Python environment, run this command:
+
+.. code::
+
+    pip install -e .
+
+
+As detailed in :ref:`licensing`, a standalone DPF Server is protected using the license terms specified in the
+`DPFPreviewLicenseAgreement <https://download.ansys.com/-/media/dpf/dpfpreviewlicenseagreement.ashx?la=en&hash=CCFB07AE38C638F0D43E50D877B5BC87356006C9>`_
+file, which is available on the `DPF Pre-Release page <https://download.ansys.com/Others/DPF%20Pre-Release>`_
+of the Ansys Customer Portal.
+To accept these terms, you must set this environment variable:
+
+.. code::
+
+    ANSYS_DPF_ACCEPT_LA=Y
+
+To use :ref:`licensed DPF capabilities <target_to_ansys_license_mechanism>` you must set the
+``ANSYSLMD_LICENSE_FILE`` environment variable to point to a valid local or remote license
+following indications in :ref:`configure_licensing`.
+
+
+Use DPF Server
+--------------
+
+DPF Server is protected using the license terms specified in the
+`DPFPreviewLicenseAgreement <https://download.ansys.com/-/media/dpf/dpfpreviewlicenseagreement.ashx?la=en&hash=CCFB07AE38C638F0D43E50D877B5BC87356006C9>`_
+file, which is available on the `DPF Pre-Release page <https://download.ansys.com/Others/DPF%20Pre-Release>`_
+of the Ansys Customer Portal.
+
+Run 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 can be used with DPF Server. Installation instructions
+for PyDPF-Core are available in the PyDPF-Core `Getting started <https://dpf.docs.pyansys.com/version/stable/getting_started/install.html>`_.
+Installation instructions for PyDPF-Post are available in the PyDPF-Post `Getting started <https://post.docs.pyansys.com/version/stable/getting_started/install.html>`_.
+
+With PyDPF-Core and PyDPF-Post, the first creation of most DPF entities starts a DPF Server with the current default configuration and context.
+For example, the following code automatically starts a DPF Server behind the scenes:
+
+.. code::
+
+    from ansys.dpf import core as dpf
+    data_sources = dpf.DataSources()
+
+With PyDPF-Core, you can also explicitly start a DPF Server using this code:
+
+.. code::
+
+    from ansys.dpf import core as dpf
+    server = dpf.start_local_server()
+
+To start a DPF Server from outside a Python environment, you can also use the execution script provided with your DPF Server package.
+On Windows, start the DPF Server by running the ``Ans.Dpf.Grpc.bat`` file in the unzipped package.
+On Linux, start the DPF Server by running the ``Ans.Dpf.Grpc.sh`` file in the unzipped package.
+
+Manage multiple DPF Server installations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PyDPF automatically starts a local instance of a DPF Server when you run a method requiring a
+connection to a server, or when you use the ``start_local_server()`` method.
+The ``start_local_server()`` method allows to choose, if necessary, which DPF Server installation
+to use thanks to its ``ansys_path`` argument.
+PyDPF otherwise follows the logic below to automatically detect and choose which locally installed
+version of DPF Server to run:
+
+- it uses the ``ANSYS_DPF_PATH`` environment variable in priority if set and targeting a valid path to a DPF Server installation.
+- it then checks the currently active Python environment for any installed standalone DPF Server, and uses the latest version available.
+- it then checks for ``AWP_ROOTXXX`` environment variables, which are set by the **Ansys installer**, and uses the latest version available.
+- if then raises an error if all of the steps above failed to return a valid path to a DPF Server installation.
+
+Run DPF Server in a Docker container
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+DPF Server can be run in a Docker container.
+
+#. Along with the ``ansys_dpf_server_lin_v2024.2.pre0.zip`` file mentioned earlier
+   in :ref:`Install DPF Server <target_installing_server>`, download the ``Dockerfile`` file.
+#. Optional: download any other plugin ZIP file as appropriate. For example, to access the ``composites`` plugin for Linux, 
+   download ``ansys_dpf_composites_lin_v2024.2.pre0.zip``.
+#. Copy all the ZIP files and ``Dockerfile`` file in a folder and navigate into that folder.
+#. To build the DPF Docker container, run the following command:
+
+.. code::
+
+    docker build . -t dpf-core:v2024.2.pre0 --build-arg DPF_VERSION=242
+
+5. To run the DPF Docker container, license it. For more information, see :ref:`DPF Preview License Agreement<target_to_license_terms>`.

doc/source/getting_started/index.rst

@@ -15,66 +15,38 @@
 through the network using gRPC or directly in the same process.
 
 
-Install PyDPF-Core
-------------------
-
-To install PyDPF-Core, in a Python environment, run this command:
-
-.. code::
-
-   pip install ansys-dpf-core
-
-For more installation options, see :ref:`Installation section <installation>`.
-
-
 Install DPF Server
 ------------------
 
+To use PyDPF-Core, you need access to a DPF Server.
+
 * DPF Server is packaged within the **Ansys installer** in Ansys 2021 R1 and later.
-  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 <target_environment_variable_with_dpf_section>`. For information on getting
-  a licensed copy of Ansys, visit the `Ansys website <https://www.ansys.com/>`_.
+  To use it, download the standard installation using your preferred distribution channel,
+  and install Ansys following the installer instructions.
+  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 
+* DPF Server pre-releases are also available as **standalone** packages (independent of the Ansys installer) on the
   `DPF Pre-Release page <https://download.ansys.com/Others/DPF%20Pre-Release>`_ of the Ansys Customer Portal.
-  As explained in :ref:`Ansys licensing <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:
-
-.. card::
+  As explained in :ref:`ref_licensing`, the standalone DPF Server is still protected by an Ansys license mechanism
+  and requires accepting the :ref:`DPF Preview License Agreement<target_to_license_terms>`.
+  Once you have access to an Ansys license, follow the guidelines to :ref:`install a standalone DPF Server <target_installing_server>`.
 
-    * Download the ``ansys_dpf_server_win_v2023.2.pre1.zip`` or ``ansys_dpf_server_lin_v2023.2.pre1.zip``
-      file as appropriate.
-    * Unzip the package and go to its root folder (``ansys_dpf_server_win_v2023.2.pre1`` or
-       ``ansys_dpf_server_lin_v2023.2.pre1``).
-    * In a Python environment, run this command:
+For more information regarding installing, managing and running DPF servers, see :ref:`ref_dpf_server`.
 
-    .. code::
-
-        pip install -e .
-
-    * DPF Server is protected using the license terms specified in the
-      `DPFPreviewLicenseAgreement <https://download.ansys.com/-/media/dpf/dpfpreviewlicenseagreement.ashx?la=en&hash=CCFB07AE38C638F0D43E50D877B5BC87356006C9>`_
-      file, which is available on the `DPF Pre-Release page <https://download.ansys.com/Others/DPF%20Pre-Release>`_
-      of the Ansys Customer Portal. To accept these terms, you must set this
-      environment variable:
-
-    .. code::
+Install PyDPF-Core
+------------------
 
-        ANSYS_DPF_ACCEPT_LA=Y
+To install PyDPF-Core, in a Python environment, run this command:
 
-For more information about the license terms, see :ref:`DPF Preview License Agreement<target_to_license_terms>`.
+.. code::
 
-To use a remote license, set the ``ANSYSLMD_LICENSE_FILE`` environment
-variable to point to the Ansys license server ``<license_server_to_use>``:
+   pip install ansys-dpf-core
 
-.. code::
+Be sure to check the :ref:`compatibility guidelines <ref_compatibility>` to know if your
+DPF Server version is compatible with the latest version of PyDPF-Core.
 
-    ANSYSLMD_LICENSE_FILE=1055@<license_server_to_use>
+For more installation options, see :ref:`Installation section <installation>`.
 
-For installation methods that do not use `pip <https://pypi.org/project/pip/>`_,
-such as using **Docker containers**, see :ref:`ref_getting_started_with_dpf_server`.
 
 Use PyDPF-Core
 --------------
@@ -140,8 +112,10 @@
 
 .. toctree::
    :hidden:
-
-   compatibility
+
    install
+   dpf_server
+   compatibility
+   licensing
    dependencies