API edits and miscellanous format fixes

Author: PipKat

README.rst

@@ -43,9 +43,9 @@ The documentation has these sections:
 - `Getting started <https://ansys.tools.docs.pyansys.com/version/stable/getting_started/index.html>`_: Learn
   how to install Ansys Common Tools in user mode.
 - `User guide <https://ansys.tools.docs.pyansys.com/version/stable/user_guide/index.html>`_: Understand key
-  concepts for implementing its tools in your workflows.
+  concepts for implementing the tools in your workflows.
 - `API reference <https://ansys.tools.docs.pyansys.com/version/stable/api/index.html>`_: Understand how to
-  use Python to interact programmatically with its tools.
+  use Python to interact programmatically with the tools.
 - `Contribute <https://ansys.tools.docs.pyansys.com/version/stable/contributing.html>`_: Learn how to
   contribute to the Ansys Common Tools codebase or documentation.
 

doc/changelog.d/45.documentation.md

@@ -1 +1 @@
-Update docstrings.
+Update documentation strings.

doc/source/contributing.rst

@@ -6,18 +6,16 @@ Contribute
 Overall guidance on contributing to a PyAnsys library appears in the
 `Contributing <https://dev.docs.pyansys.com/how-to/contributing.html>`_ topic
 in the *PyAnsys developer's guide*. Ensure that you are thoroughly familiar
-with this guide before attempting to contribute to the Ansys Common Tools repository.
+with this guide before attempting to contribute to Ansys Common Tools.
 
-The following contribution information is specific to the Ansys Common Tools.
+The following contribution information is specific to Ansys Common Tools.
 
 Install in developer mode
 -------------------------
 
-Installing the Ansys tools in developer mode allows you to modify and enhance
-the source.
+Installing Ansys Common Tools in developer mode allows you to modify and enhance the source.
 
-To clone and install the latest Ansys tools release in development mode, run
-these commands:
+To clone and install the latest Ansys Common Tools release in development mode, run these commands:
 
 .. code::
 
@@ -29,22 +27,20 @@ these commands:
 Run tests
 ---------
 
-Ansys tools common uses `pytest <https://docs.pytest.org/en/stable/>`_ for testing.
+Ansys Common Tools uses `pytest <https://docs.pytest.org/en/stable/>`_ for testing.
 
-#. Prior to running tests, you must run this command to install
-   test dependencies::
+#. Prior to running tests, you must run this command to install test dependencies::
 
     pip install -e .[tests]
 
-#. To then run the tests, navigate to the root directory of the repository and run this
-   command::
+#. To then run the tests, navigate to the root directory of the repository and run this command::
 
     pytest
 
 Adhere to code style
 --------------------
 
-The Ansys Common Tools follows the PEP8 standard as outlined in
+Ansys Common Tools follows the PEP8 standard as outlined in
 `PEP 8 <https://dev.docs.pyansys.com/coding-style/pep8.html>`_ in
 the *PyAnsys developer's guide* and implements style checking using
 `pre-commit <https://pre-commit.com/>`_.
@@ -76,7 +72,7 @@ This way, it's not possible for you to push code that fails the style checks::
 Build the documentation
 -----------------------
 
-You can build the Ansys Common Tools documentation locally.
+You can build Ansys Common Tools documentation locally.
 
 #. Prior to building the documentation, you must run this command to install
    documentation dependencies::
@@ -105,11 +101,10 @@ You can clean the documentation build by running this command::
 Post issues
 -----------
 
-Use the `Ansys tools common Issues <https://github.com/ansys/ansys-tools-common/issues>`_
-page to report bugs and request new features. When possible, use the issue templates provided.
+Use the Ansys Common Tools `Issues <https://github.com/ansys/ansys-tools-common/issues>`_ page to report bugs and request new features. When possible, use the issue templates provided.
 If your issue does not fit into one of these templates, click the link for opening a blank issue.
 
 If you have general questions about the PyAnsys ecosystem, email
 `[email protected] <[email protected]>`_. If your
-question is specific to the Ansys Common Tools, ask your
+question is specific to Ansys Common Tools, ask your
 question in an issue as described in the previous paragraph.

doc/source/index.rst

@@ -20,7 +20,7 @@ Ansys Common Tools provides a collection of tools for the PyAnsys ecosystem.
         :link: user_guide/index
         :link-type: doc
 
-        Understand key concepts for implementing its tools
+        Understand key concepts for implementing the tools
         in your workflows.
 
 
@@ -29,15 +29,14 @@ Ansys Common Tools provides a collection of tools for the PyAnsys ecosystem.
         :link: api/index
         :link-type: doc
 
-        Understand how to use Python to interact programmatically with
-        its tools.
+        Understand how to use Python to interact programmatically with the tools.
 
     .. grid-item-card:: Contribute :material-regular:`group`
         :padding: 2 2 2 2
         :link: contributing
         :link-type: doc
 
-        Learn how to contribute to the Ansys tools codebase or documentation.
+        Learn how to contribute to the Ansys Common Tools codebase or documentation.
 
 
 

src/ansys/tools/common/abstractions/__init__.py

@@ -19,7 +19,7 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
-"""Init module for abstractions."""
+"""Initialization module for abstractions."""
 
 from .connection import AbstractGRPCConnection  # noqa F401
 from .launcher import LauncherProtocol  # noqa F401

src/ansys/tools/common/abstractions/connection.py

@@ -39,9 +39,9 @@ class AbstractGRPCConnection(ABC):
     Parameters
     ----------
     host : str
-        The host where the gRPC server is running.
+        Host where the gRPC server is running.
     port : str
-        The port where the gRPC server is listening.
+        Port where the gRPC server is listening.
     """
 
     @abstractmethod
@@ -62,12 +62,12 @@ def close(self) -> None:
     @property
     @abstractmethod
     def service(self):
-        """Return the gRPC stub for making requests."""
+        """GRPC stub for making requests."""
         pass  # pragma: no cover
 
     @property
     def _host(self) -> str:
-        """Return the host for the gRPC connection."""
+        """Host for the gRPC connection."""
         return self.__host
 
     @_host.setter
@@ -92,12 +92,12 @@ def _channel(self, options: list = None) -> grpc.Channel:
 
     @property
     def is_closed(self) -> bool:
-        """Check if the connection is closed.
+        """Flag indicating if the connection is closed.
 
         Returns
         -------
         bool
-            True if the connection is closed, False otherwise.
+            ``True`` if the connection is closed, ``False`` otherwise.
         """
         try:
             return self._channel._connectivity_state != grpc.ChannelConnectivity.READY

src/ansys/tools/common/abstractions/launcher.py

@@ -22,8 +22,7 @@
 
 """Interface definitions for implementing a local product launcher.
 
-A plugin for the Local Product Launcher must implement the :class:`LauncherProtocol`
-class and register it.
+A plugin for the local product launcher must implement the :class:`LauncherProtocol` class and register it.
 """
 
 from enum import Enum, auto
@@ -44,8 +43,7 @@ class and register it.
 
 METADATA_KEY_NOPROMPT = "launcher_noprompt"
 """
-Key used in the :py:class:`dataclasses.Field` ``metadata`` to skip prompting for
-the option by default.
+Key used in the :py:class:`dataclasses.Field` ``metadata`` to skip prompting for the option by default.
 """
 
 FALLBACK_LAUNCH_MODE_NAME = "__fallback__"
@@ -67,8 +65,7 @@ class ServerType(Enum):
     """Defines which protocols the server supports.
 
     The ``ServerType`` class is used as values in the :attr:`LauncherProtocol.SERVER_SPEC`
-    attribute to define the capabilities of the servers started with a given product and
-    launch method.
+    attribute to define the capabilities of the servers started with a given product and launch method.
     """
 
     GENERIC = auto()
@@ -87,43 +84,41 @@ class ServerType(Enum):
 
 
 class LauncherProtocol(Protocol[LAUNCHER_CONFIG_T]):
-    """Interface for managing a local product instance.
+    """Provides the interface for managing a local product instance.
 
-    A plugin to the Local Product Launcher must implement the interface
-    defined in this class.
+    A plugin to the local product launcher must implement the interface defined in this class.
 
-    To check for compatibility, it is recommended to derive from this
-    class, for example ``MyLauncher(LauncherProtocol[MyConfigModel])``, and
-    check the resulting code with `mypy <https://mypy.readthedocs.io>`_.
+    To check for compatibility, you should derive from this
+    class. For example ``MyLauncher(LauncherProtocol[MyConfigModel])``.
+    Check the resulting code with `Mypy <https://mypy.readthedocs.io>`_.
 
     The ``__init__`` method should accept exactly one keyword-only
-    parameter: ``config``. Note that this is `not enforced by mypy
-    <https://bugs.python.org/issue44807>`_.
+    parameter: ``config``. Note that this is `not enforced by
+    Mypy <https://bugs.python.org/issue44807>`_.
 
     Parameters
     ----------
     config :
-        Configuration options used to start the product. This parameter
-        must be an instance of ``CONFIG_MODEL``.
+        Configuration options used to start the product. This parameter must be an instance of ``CONFIG_MODEL``.
     """
 
     CONFIG_MODEL: type[LAUNCHER_CONFIG_T]
     """Defines the configuration options for the launcher.
 
-    The configuration options which this launcher accepts, specified
-    as a :py:func:`dataclass <dataclasses.dataclass>`. Note that the
-    ``default`` and ``metadata[METADATA_KEY_DOC]`` of the fields are
-    used in the configuration CLI, if available.
+    The configuration options that this launcher accepts, specified
+    as a :py:func:`dataclass <dataclasses.dataclass>`. Note that
+    the ``default`` and ``metadata[METADATA_KEY_DOC]`` of the
+    fields are used in the configuration CLI, if available.
     """
 
     SERVER_SPEC: dict[str, ServerType]
     """Defines the server types that are started.
 
     Examples
     --------
-    This code defines a server that is accessible via a URL at the
-    ``"MAIN"`` key and a server accessible via gRPC at the
-    ``"FILE_TRANSFER"`` key.
+    This code defines a server that is accessible via a URL
+    at the ``"MAIN"`` key and a server accessible via gRPC
+    at the ``"FILE_TRANSFER"`` key.
 
     .. code:: python
 
@@ -149,8 +144,7 @@ def stop(self, *, timeout: float | None = None) -> None:
         timeout :
             Time after which the instance can be forcefully stopped.
             The timeout should be interpreted as a hint to the implementation.
-            It is *not required* to trigger a force-shutdown, but the stop
-            *must* return within a finite time.
+            It is *not required* to trigger a force-shutdown, but the stop *must* return within a finite time.
         """
 
     def check(self, *, timeout: float | None = None) -> bool:
@@ -161,20 +155,21 @@ def check(self, *, timeout: float | None = None) -> bool:
         timeout :
             Timeout in seconds for the check.
             The timeout should be interpreted as a hint to the implementation.
-            It is *not required* to return within the given time, but the
-            check *must* return within a finite time, meaning it must not
-            hang indefinitely.
+            It is *not required* to return within the given time,
+            but the check *must* return within a finite time,
+            meaning it must not hang indefinitely.
 
         Returns
         -------
-        :
+        bool
             Whether the product instance is responding.
         """
 
     @property
     def urls(self) -> dict[str, str]:
         """Dictionary of URLs that the server is listening on.
 
-        The keys of the returned dictionary must correspond to the keys
-        defined in the :attr:`.LauncherProtocol.SERVER_SPEC` attribute.
+        The keys of the returned dictionary must correspond
+        to the keys defined in the
+        :attr:`.LauncherProtocol.SERVER_SPEC` attribute.
         """