docs: improve secure connection communication (#2423)

Co-authored-by: pyansys-ci-bot <[email protected]>

Author: RobPasMue

doc/changelog.d/2423.documentation.md

@@ -0,0 +1 @@
+Improve secure connection communication

doc/source/getting_started/existing/index.rst

@@ -22,11 +22,21 @@ From Python, establish a connection to the existing client session by creating a
 
     from ansys.geometry.core import Modeler
 
-    modeler = Modeler(host="localhost", port=50051)
+    modeler = Modeler(host="localhost", port=50051, transport_mode="wnua")  # On Windows
+    # or
+    modeler = Modeler(host="localhost", port=50051, transport_mode="uds")  # On Linux
+    # or
+    modeler = Modeler(host="localhost", port=50051, transport_mode="insecure")  # For any OS using insecure gRPC
 
 If no error messages are received, your connection is established successfully.
 Note that your local port number might differ from the one shown in the preceding code.
 
+.. note::
+
+    Starting from PyAnsys Geometry 0.14, the ``transport_mode`` parameter is required.
+    For detailed information about available transport modes, secure connections, and
+    compatibility with different Ansys releases, see :ref:`user_guide_connection_securing`.
+
 Verify the connection
 ---------------------
 If you want to verify that the connection is successful, request the status of the client

doc/source/getting_started/local/index.rst

@@ -70,6 +70,11 @@ their API documentation:
 * `launch_modeler_with_spaceclaim <../../api/ansys/geometry/core/connection/launcher/index.html#launcher.launch_modeler_with_spaceclaim>`_
 * `launch_modeler_with_geometry_service <../../api/ansys/geometry/core/connection/launcher/index.html#launcher.launch_modeler_with_geometry_service>`_
 
+.. note::
+
+    For information about transport modes and secure connections, see the
+    :ref:`user_guide_connection_securing` section in the User Guide.
+
 .. note::
 
     Because this is the first release of the Geometry service, you cannot yet define a product version

doc/source/user_guide/connection.rst

@@ -18,12 +18,27 @@ To connect to a Modeler instance, you can use the  :class:`Modeler() <ansys.geom
 which provides methods to connect to the desired CAD service. You can specify the connection parameters such
 as the host, port, and authentication details.
 
+
 .. code:: python
 
     from ansys.geometry.core import Modeler
 
     # Connect to a local Modeler instance
-    modeler = Modeler(host="localhost", port=12345)
+    modeler = Modeler(host="localhost", port=12345, transport_mode=...)
+
+The ``transport_mode`` parameter can take several values depending on the type of connection you
+want to establish. You can refer to the `Securing connections`_ section for more details on the
+available transport modes.
+
+.. warning:: Required ``transport_mode`` parameter
+
+   Starting from PyAnsys Geometry 0.14, the ``transport_mode`` parameter is required when using
+   the ``Modeler()`` class. Only if the ``channel`` parameter is provided explicitly, the
+   ``transport_mode`` can be omitted.
+
+However, if you are using the :func:`launch_modeler() <ansys.geometry.core.connection.launcher>`
+function to launch a local Modeler instance, the ``transport_mode`` parameter is optional and
+defaults to the appropriate mode based on the operating system and environment.
 
 Connection types
 ----------------
@@ -37,13 +52,24 @@ differ in the environment in which the transport takes place:
   Modeler client connects to it over the network. This is useful for accessing
   Modeler instances hosted on remote servers or cloud environments.
 
+.. _user_guide_connection_securing:
+
 Securing connections
 --------------------
 
 When connecting to a remote Modeler instance, it is important to ensure that the connection
 is secure, not only to protect sensitive data but also to comply with organizational
 security policies. These secure connections can be established using various methods, such as:
 
+.. warning:: Secure connection compatibility
+
+   Secure connections (mTLS, UDS, WNUA) are only available starting from Ansys release 24R2.
+   However, some releases may require specific Service Packs to enable secure connection support.
+   Starting from Ansys release 26R1, secure connections are available out-of-the-box without
+   requiring additional Service Packs.
+
+   If you are using an Ansys release prior to 24R2, you must use insecure connections.
+
 - **mTLS**: Mutual Transport Layer Security (mTLS) is a security protocol that ensures both the client
   and server authenticate each other using digital certificates. This provides a high level of
   security for the connection. PyAnsys Geometry supports mTLS connections to Modeler instances. In that

src/ansys/geometry/core/connection/client.py

@@ -174,7 +174,9 @@ def wait_until_healthy(
             raise ValueError(
                 "Transport mode must be specified."
                 " Use 'transport_mode' parameter with one of the possible options."
-                " Options are: 'insecure', 'uds', 'wnua', 'mtls'."
+                " Options are: 'insecure', 'uds', 'wnua', 'mtls'. See the following"
+                " documentation for more details:"
+                " https://geometry.docs.pyansys.com/version/stable/user_guide/connection.html#securing-connections"
             )
         else:
             from ansys.tools.common.cyberchannel import verify_transport_mode