Docs/fixes and minor edits

README.rst

@@ -16,7 +16,7 @@ It also provides how-to information and summarizes packaging, coding, and
 documentation styles. It concludes with an abstractions section that explains
 how apps and complex services expose only functionalities that matter to users.
 
-From the **About** area for the repository, you can click the link for the latest web-based
-release of this guide. In the `Releases <https://github.com/ansys/pyansys-dev-guide/releases>`_
+From the **About** area for the repository, you can click the link to view
+the latest web-based release of this guide. In the `Releases <https://github.com/ansys/pyansys-dev-guide/releases>`_
 area, you can view information about all releases. In the **Assets**  area for
-any release, you can download a PDF.
+any release, you can download a PDF file of the guide.

doc/source/abstractions/data-transfer.rst

@@ -102,7 +102,7 @@ languages and its efficiency over REST in terms of speed, memory, and
 payload size.
 
 Typically, REST data exchanges should be limited to short messages
-transferred via JSON files, and gRPC should be used for large data
+that are transferred using JSON files, and gRPC should be used for large data
 transfers and bidirectional streaming.
 
 Choosing gRPC over REST is generally preferable due to the performance

doc/source/abstractions/service.rst

@@ -55,13 +55,13 @@ The approach on the right has a number of advantages, including:
 - Simplified interface for starting MAPDL
 - Full documentation strings for all classes, methods, and functions
 
-To properly abstract a service, users must have the option to
+To properly abstract a service, you must have the option to
 either launch the service and connect to it locally if the software exists on
-their machines or connect to a remote instance of the service. One
+your machines or connect to a remote instance of the service. One
 way to do this is to include a function to launch the service.
 
-This example includes ``launch_mapdl``, which brokers a connection via the 
-``Mapdl`` class:
+This example includes the ``launch_mapdl`` function, which brokers a connection with
+the ``Mapdl`` class:
 
 .. code:: pycon
 
@@ -74,7 +74,7 @@ This example includes ``launch_mapdl``, which brokers a connection via the
    ansys.mapdl Version: 0.59.dev0
 
 This straightforward approach connects to a local or remote instance 
-of MAPDL via gRPC by instantiating an instance of the ``Mapdl`` class. 
+of MAPDL using gRPC by instantiating an instance of the ``Mapdl`` class. 
 At this point, because the assumption is that MAPDL is always remote, it's 
 possible to issue commands to MAPDL, including those requiring 
 file transfer like ``Mapdl.input``.

doc/source/all-styles.rst

@@ -3,33 +3,33 @@ Style
 =====
 
 In the PyAnsys ecosystem, three key styles contribute to an 
-enhanced developer experience: packaging style, coding style, and documentation style
+enhanced developer experience:
 
-- Packaging style focuses on creating clear, open source APIs hosted on GitHub,allowing
+- **Packaging style**: Focuses on creating clear, GitHub-hosted open source APIs, allowing
   for reusable packages that can be updated independently of the Ansys release schedule.
-- Coding style adheres to `PEP 8`_ and aligns with the conventions of major data science packages
-  like `numpy`_, `scipy`_, and `pandas`_, ensuring consistency and readability.
-- Documentation style emphasizes the significance of well-documented APIs,
-  offering increased adoption, an improved on-boarding experiences, and streamlined code maintenance.
+- **Coding style**: Ensures that code adheres to `PEP 8`_ and aligns with the conventions of
+  major data science packages like `NumPy`_, `SciPy`_, and `pandas`_ for consistency and readability.
+- **Documentation style**: Emphasizes the significance of cohesive and user-friendly
+  content and well-documented APIs to improve the on-boarding experience and increase library adoption.
   All PyAnsys libraries follow the `Google developer documentation style guide
-  <https://developers.google.com/style/>`_, incorporating sentence case, 
-  active voice, and concise, clear sentences for cohesive and user-friendly documentation.
+  <https://developers.google.com/style/>`_, which includes using sentence-case titles, active voice,
+  present tense, and clear, concise sentences.
 
 .. grid:: 3
 
-    .. grid-item-card:: :octicon:`file-directory` Packaging
+    .. grid-item-card:: :octicon:`file-directory` Packaging style
         :link: packaging/index
         :link-type: doc
 
         Best practices for distributing Python code.
 
-    .. grid-item-card:: :octicon:`codespaces` Coding
+    .. grid-item-card:: :octicon:`codespaces` Coding style
         :link: coding-style/index
         :link-type: doc
 
         Best practices for writing Python code.
 
-    .. grid-item-card:: :octicon:`pencil` Documentation
+    .. grid-item-card:: :octicon:`pencil` Documentation style
         :link: doc-style/index
         :link-type: doc
 

doc/source/coding-style/deprecation.rst

@@ -2,17 +2,18 @@ Deprecation best practices
 ==========================
 
 While deprecation best practices are outlined in 
-this `Deprecation library <https://deprecation.readthedocs.io/>`_ ,
+this `deprecation documentation <https://deprecation.readthedocs.io/>`_,
 there is no official guidance on deprecating features within Python.
 Thus, this topic provides deprecation best practices for PyAnsys
 libraries. 
 
-Whenever you deprecate a method, class, or function, you must either:
+Whenever you deprecate a method, class, or function, you must take one of
+these actions:
 
-- Have the old method call the new method and raise a warning
-- Raise an ``AttributeError`` if you remove the method entirely
+- Have the old method call the new method and raise a warning.
+- Raise an ``AttributeError`` if you remove the method entirely.
 
-In the docstring of the old method, provide a `Sphinx Deprecated Directive
+In the docstring of the old method, use a Sphinx `deprecated directive
 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated>`_
 that links to the new method. This way, you notify your users when you make
 an API change and give them a chance to change their code. Otherwise,

doc/source/coding-style/formatting-tools.rst

@@ -19,30 +19,30 @@ maintained by the Python Software Foundation. It allows for a minimum
 configuration to ensure that the Python code format looks almost the same across
 projects. 
 
-While `PEP 8`_ imposes a default line length of 79 characters, `black`_ has
+While `PEP 8`_ imposes a default line length of 79 characters, Black has
 a default line length of 88 characters.
 
-The minimum `black`_ configuration for a PyAnsys project should look like this:
+The minimum Black configuration for a PyAnsys project should look like this:
 
 .. code-block:: toml
 
     [tool.black]
     line-length = "<length>"
 
 
-The ``isort``
--------------
+The ``isort`` tool
+------------------
 
 The goal of `isort`_  is to properly format ``import`` statements by making sure
 that they follow the standard order:
 
-#. library
-#. third-party libraries
-#. custom libraries
+#. Library
+#. Third-party libraries
+#. Custom libraries
 
 When using `isort`_ with `Black`_, it is important to properly configure both
 tools so that no conflicts arise. To accomplish this, use the
-``--profile black`` flag in `isort`_.
+``--profile black`` flag in ``isort``.
 
 .. code-block:: toml
 
@@ -56,14 +56,14 @@ tools so that no conflicts arise. To accomplish this, use the
 Flake8
 ------
 
-The goal of `Flake8` is to act as a `PEP 8`_ compliance checker. Again, if
+The goal of `Flake8`_ is to act as a `PEP 8`_ compliance checker. Again, if
 this tool is being used with `Black`_, it is important to make sure that no
 conflicts arise.
 
-The following configuration is the minimum one to set up `flake8`_ together with
-`black`_.
+The following configuration is the minimum one to set up Flake8 together with
+Black.
 
-The configuration for `flake8`_ must be specified in a ``.flake8`` file.
+The configuration for Flake8 must be specified in a ``.flake8`` file.
 
 .. code-block:: toml
 
@@ -72,8 +72,9 @@ The configuration for `flake8`_ must be specified in a ``.flake8`` file.
    extend-ignore = 'E203'
 
 Flake8 has many options that can be set within the configuration file.
-For more information, see this `Flake8 documentation topic
-<https://flake8.pycqa.org/en/latest/user/options.html>`__.
+For more information, see `Full Listing of Options and Their Descriptions
+<https://flake8.pycqa.org/en/latest/user/options.html>`__ in the Flake8
+documentation.
 
 The example configuration defines these options:
 
@@ -83,35 +84,35 @@ The example configuration defines these options:
 - ``select``
     Sequence of error codes that Flake8 is to report errors
     for. The set in the preceding configuration is a basic set of errors
-    for checking and is not an exhaustive list.
-
-    For a full list of error codes and their descriptions, see this `Flake8
-    documentation topic <https://flake8.pycqa.org/en/3.9.2/user/error-codes.html>`__.
+    for checking and is not an exhaustive list. For more information, see
+    `Error/Violation Codes <https://flake8.pycqa.org/en/3.9.2/user/error-codes.html>`__
+    in the Flake8 documentation.
 
 - ``count``
     Total number of errors to print when checking ends.
 
 - ``max-complexity``
-   Maximum allowed McCabe complexity value for a block of code.
+    Maximum allowed McCabe complexity value for a block of code.
     The value of 10 was chosen because it is a common default.
 
 - ``statistics``
     Number of occurrences of each error or warning code
     to print as a report when checking ends.
 
 
-Add-license-headers
--------------------
+The ``Add-license-headers`` pre-commit hook
+-------------------------------------------
 
 The goal of the ``add-license-headers`` pre-commit hook is to add and update license headers
-for files with `REUSE <https://reuse.software/>`_. By default, the hook runs on
+for files with `REUSE <https://reuse.software/>`_ software. By default, the hook runs on
 PROTO files in any directory and on Python files in the ``src``, ``examples``, and ``tests`` directories.
 
-You can find the MIT license that is added to the files in
-`ansys/pre-commit-hooks repository - MIT.txt
-<https://github.com/ansys/pre-commit-hooks/blob/main/src/ansys/pre_commit_hooks/assets/LICENSES/MIT.txt>`_.
+You can find in the ``ansys/pre-commit-hooks`` repository, the `MIT.txt
+<https://github.com/ansys/pre-commit-hooks/blob/main/src/ansys/pre_commit_hooks/assets/LICENSES/MIT.txt>`_ file
+that is added to files.
 
-For information on customizing the hook, see the `README <https://github.com/ansys/pre-commit-hooks/blob/main/README.rst>` file.
+For information on customizing the hook, in this same repository, see the
+`README <https://github.com/ansys/pre-commit-hooks/blob/main/README.rst>`_ file.
 
 Code coverage
 -------------
@@ -124,7 +125,7 @@ For PyAnsys libraries, code coverage is done using `pytest-cov`_, a `pytest`_ pl
 that triggers code coverage analysis once your test suite has executed.
 
 Considering the layout presented in :ref:`Required files`, the following
-configuration for code coverage is the minimum one required for a ``PyAnsys``
+configuration for code coverage is the minimum one required for a PyAnsys
 project:
 
 .. code-block:: toml
@@ -135,18 +136,17 @@ project:
    [tool.coverage.report]
    show_missing = true
 
-The ``pre-commit``
-------------------
+The ``pre-commit`` tool
+-----------------------
 
 To ensure that every commit you make is compliant with the code style
 guidelines for PyAnsys, you can take advantage of `pre-commit`_ in your project.
-Every time you stage some changes and try to commit them, `pre-commit`_ only
+Every time you stage some changes and try to commit them, ``pre-commit`` only
 allows them to be committed if all defined hooks succeed.
 
-The configuration for `pre-commit`_ must be defined in a
+You must define the configuration for ``pre-commit`` in a
 ``.pre-commit-config.yaml`` file. The following lines present a minimum
-`pre-commit`_ configuration that includes both code and documentation
-formatting tools.
+configuration that includes both code and documentation formatting tools.
 
 .. code-block:: yaml
 
@@ -184,48 +184,47 @@ formatting tools.
       hooks:
       - id: add-license-headers
 
-Installing ``pre-commit``
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Install ``pre-commit``
+~~~~~~~~~~~~~~~~~~~~~~
 
-You can install ``pre-commit`` by running:
+You can install ``pre-commit`` by running this command:
 
 .. code-block:: bash
 
     python -m pip install pre-commit
 
-Then, ensure that you install it as a ``Git hook`` by running:
+Then, ensure that you install it as a ``Git hook`` by running this command:
 
 .. code-block:: bash
 
     pre-commit install
 
-Using ``pre-commit``
-~~~~~~~~~~~~~~~~~~~~
+Use ``pre-commit``
+~~~~~~~~~~~~~~~~~~
 
 One installed as described, ``pre-commit`` automatically triggers every time
-that you try to commit a change. If any hook defined in `.pre-commit-config.yaml`
-fails, you must fix the failing files, stage the new changes, and try to commit
+that you try to commit a change. If any hook defined in the ``.pre-commit-config.yaml``
+file fails, you must fix the failing files, stage the new changes, and try to commit
 them again.
 
-If you want to manually run ``pre-commit``, you can run:
+If you want to manually run ``pre-commit``, run this command:
 
 .. code-block:: bash
 
     pre-commit run --all-files --show-diff-on-failure
 
-This command shows the current and expected style of the code if any of
-the hooks fail.
+If any of the hooks fail, this command shows the current and expected style of the code.
 
-Tox
----
+The ``tox`` tool
+----------------
 
 You might consider using `tox`_ in your project. While this automation
 tool is similar to `Make`_, it supports testing of your package in a temporary
 virtual environment. Being able to test your package in isolation rather than in
 "local" mode guarantees reproducible builds.
 
-Configuration for `tox`_ is stored in a ``tox.ini`` file. The minimum
-configuration for a PyAnsys ``py<product>-<library>`` project should be:
+Configuration for ``tox`` is stored in a ``tox.ini`` file. Here is the minimum
+configuration for a PyAnsys ``py<product>-<library>`` project:
 
 .. tab-set::
 
@@ -242,26 +241,28 @@ contains ``requirements_tests.txt`` and ``requirements_doc.txt`` files. In
 addition, the ``style`` environment must execute ``pre-commit``, which guarantees
 the usage of this tool in your project.
 
-Installing ``tox``
-~~~~~~~~~~~~~~~~~~
+Install ``tox``
+~~~~~~~~~~~~~~~
 
 You can install ``tox`` like any other Python package:
 
 .. code-block:: bash
 
     python -m pip install tox
 
-Using ``tox``
-~~~~~~~~~~~~~
+Use ``tox``
+~~~~~~~~~~~
 
-`tox`_ uses ``environments``, which are similar to ``Makefile`` rules,
+The ``tox`` tool uses ``environments``, which are similar to ``Makefile`` rules,
 to make it highly customizable. Descriptions follow of some of the most
 widely used environments:
 
 - ``tox -e style``: Checks the code style of your project.
 - ``tox -e py``: Runs your test suite.
 - ``tox -e doc``: Builds the documentation of your project.
 
-It is possible to run multiple environments by separating them with commas ``tox
--e <env-name0>,<env-name1>,...```.  To run all available environments, simply
-run ``tox``.
+It is possible to run multiple environments by separating them with commas:
+
+``tox -e <env-name0>,<env-name1>,...``
+
+To run all available environments, simply type ``tox``.