Doc/general edits (#14)

* Update README.rst

* Update app_interface_abstraction.rst

* Update data_transfer_and_representation.rst

* Update index.rst

* Update service_abstraction.rst

* Update best_practices.rst

* Update data_transfer_and_representation.rst

* Update best_practices.rst

* Create best_practices.rst

* Update flake8.rst

* Update index.rst

* Update class_documentation.rst

* Update coding_style.rst

* Update docstrings.rst

* Update index.rst

* Update sample_func.py

* Update ci_cd.rst

* Update ci_cd.rst

* Update doc_directory.rst

* Update index.rst

* Update index.rst

* Update index.rst

* Update index.rst

* Update index.rst

* Update library_names.rst

* Update license.rst

* Update packaging.rst

* Update packaging.rst

* Update packaging.rst

* Update packaging.rst

* Update packaging.rst

* Update packaging.rst

* Update packaging.rst

* Update packaging.rst

* Update packaging.rst

* Update packaging.rst

* Update packaging.rst

* Update readme_file.rst

* Update repo_directory_structure.rst

* Update source_organization.rst

* Update administration.rst

* Update contributing.rst

* Update contributing.rst

* Update contributing.rst

* Update contributing.rst

* Update administration.rst

* Update dev_practices.rst

* Update dev_practices.rst

* Update index.rst

* Update index.rst

* Update index.rst

* Update index.rst

* Update index.rst

* Update index.rst

* fix links

* Apply suggestions from code review

Co-authored-by: Alex Kaszynski <[email protected]>

Author: PipKat

README.rst

@@ -3,36 +3,38 @@ PyAnsys Developer's Guide
 
 This guide serves as the central document for:
 
-- Ansys developers who want to create and "own" libraries.
+- Ansys developers who want to create and "own" libraries
 - Anyone in the Python community who wants to contribute to a 
-  library.
+  library
 - Anyone who is interested in learning more about the PyAnsys 
-  project and libraries.
+  project and libraries
 
 
-Web-based documentation will be posted upon approval.
+Web-based documentation is posted upon approval.
 
-PDF version of this guide can be found in the release notes in `Releases
+A PDF version of this guide can be found in the release notes in `Releases
 <https://github.com/pyansys/about/releases>`_.
 
 
 Generate Documentation
 ----------------------
-Generate this documentation locally by first installing the
+To generate this documentation locally, first install the
 requirements with:
 
 .. code::
 
    pip install -r requirements_docs.txt
 
-Then build (on Windows) with:
+Then, depending on your operating system, generate the documentation.
+
+On Windows, generate with:
 
 .. code::
 
    cd doc
    make.bat html
 
-Or on Linux with:
+On Linux, generate with:
 
 .. code::
 
@@ -41,6 +43,6 @@ Or on Linux with:
 
 Contributing
 ------------
-Feel free to contribute to this guide by creating a branch and
-contributing directly, or forking and submitting a PR.  All PRs will
-be reviewed before merge.
+To contribute to this guide, either create a branch and
+contribute directly or fork and submit a pull request.  All 
+pull requests are reviewed before they can be merged.

doc/source/abstraction/app_interface_abstraction.rst

@@ -13,7 +13,7 @@ recorded script from AEDT versus using the PyAEDT libary to create an
 open region in the active editor:
 
 +------------------------------------------------------+----------------------------------------------+
-| Using AEDT with MS COM Methods                       | Using AEDT with the `PyAEDT`_ Library        |
+| Using a Recorded Script from AEDT (MS COM Methods)   | Using the `PyAEDT`_ Library                  |
 +------------------------------------------------------+----------------------------------------------+
 | .. code:: python                                     | .. code:: python                             |
 |                                                      |                                              |
@@ -41,15 +41,15 @@ open region in the active editor:
 
 Besides length and readability, the biggest difference between the two
 approaches is how the methods and attributes from the ``Hfss`` class
-are encapsulated.  For example, AEDT no longer needs to be
+are encapsulated. For example, AEDT no longer needs to be
 explicitly instantiated and is hidden as a protected attribute
 ``_desktop``. The connection to the application takes place
 automatically when ``Hfss`` is instantiated, and the active AEDT 
 project, editor, and module are automatically used to create the 
 open region.
 
-Furthermore, the ``create_open_region`` method within ``Hfss`` 
-contains a full Python documentation string with keyword arguments,
+Furthermore, the ``create_open_region`` method within the ``Hfss`` 
+class contains a full Python documentation string with keyword arguments,
 clear ``numpydoc`` parameters and returns, and a basic example.
 These are unavailable when directly using COM methods, preventing
 the use of contextual help from within a Python IDE.
@@ -103,10 +103,10 @@ within this method.
 Here, the COM ``CreateOpenRegion`` method is abstracted, encapsulating
 the model setup object.  There's no reason why a user needs direct
 access to ``_omodelsetup``, which is why it's protected in the
-``Hfss`` class.  Additionally, calling the method is simplified by
+``Hfss`` class. Additionally, calling the method is simplified by
 providing (and documenting) the defaults using keyword arguments and
 placing them into the ``vars`` list, all while following the `Style
 Guide for Python Code (PEP8)`_.
 
 .. _PyAEDT: https://github.com/pyansys/PyAEDT
-.. _Style Guide for Python Code (PEP8): https://www.python.org/dev/peps/pep-0008
+.. _Style Guide for Python Code (PEP8): https://www.python.org/dev/peps/pep-0008

doc/source/abstraction/data_transfer_and_representation.rst

@@ -2,10 +2,10 @@ Data Transfer and Abstraction
 =============================
 Abstracted APIs should attempt to hide the implementation details of
 the remote or local API in a well organized data model.  This data
-model should avoid returning raw JSON, gRPC messages, SWIG objects, or
-.NET objects.  Rather, it preferable to return standard Python objects
-like lists, strings, dictionaries when useful, and NumPy arrays or
-pandas dataframes for more complex data.
+model should avoid returning raw JSON files, gRPC messages, SWIG objects,
+or .NET objects. It should preferably return standard Python objects
+like lists, strings, dictionaries when useful, and `NumPy <https://numpy.org/>`_
+arrays or `pandas <https://pandas.pydata.org/>`_ dataframes for more complex data.
 
 For example, consider a simple mesh in MAPDL:
 
@@ -16,9 +16,9 @@ For example, consider a simple mesh in MAPDL:
    >>> mapdl.et(1, 186)
    >>> mapdl.vmesh('ALL')
 
-At this point, the only two ways within MAPDL to access the nodes and
-connectivity of the mesh are either to print it using the ``NLIST``
-command or to write it to disk using the ``CDWRITE`` command. Both 
+At this point, there are only two ways within MAPDL to access the nodes and
+connectivity of the mesh, You can either print it using the ``NLIST``
+command or write it to disk using the ``CDWRITE`` command. Both of these
 methods are remarkably inefficient, requiring:
 
 - Serializing the data to ASCII on the server
@@ -65,28 +65,28 @@ within the MAPDL database.
           [0.75, 0.5 , 0.5 ]])
 
 
-REST vs RPC Data and Model Abstraction
---------------------------------------
-Because of the nature of Ansys's products, our applications and
-services can either fit into the RPC interface where the API is
-centered around operations and commands, or the REST model which is
-centered around resources.  Regardless of the the interface style,
-there are several items to consider.
+REST Versus RPC Data and Model Abstraction
+------------------------------------------
+Because of the nature of most Ansys products, our applications and
+services can either fit into the RPC interface, where the API is
+centered around operations and commands, or the REST model, where
+the API is centered around resources. Regardless of the the interface
+style, there are several items to consider.
 
 
 API Chattiness
 ~~~~~~~~~~~~~~
-APIs must be efficient to avoid creating chatty I/O.  Because many of
-Ansys's products fit well with the RPC API implementation, there is a
-temptation to design APIs that require constant communication with the
-remote or local service.  However, just because RPC interfaces can,
-does not mean they should as it should be assumed that each RPC call
-takes significant time to execute.
-
-One way to avoid this approach is to either serialize several
-"commands" for services that employ an internal "command pattern" for
-data exchange.  Another approach is to encapsulate the data model
-entirely on the server and avoid data transfer whenever possible and
+APIs must be efficient to avoid creating chatty input and output.
+Because many Ansys products fit well with the RPC API implementation,
+there is a temptation to design APIs that require constant communication
+with the remote or local service. However, just because RPC interfaces
+can do this, it does not mean that they should. The assumption should be
+that each RPC call takes significant time to execute.
+
+One way to avoid constant communication with the service is to serialize
+several "commands" for services that employ an internal "command pattern"
+for data exchange. Another approach is to encapsulate the data model
+entirely on the server to avoid data transfer whenever possible and
 expose only a limited number of RPC methods in the front-facing API.
 
 Compatibility and Efficiency
@@ -97,16 +97,15 @@ of the first choices due to its compatibility with nearly all popular
 languages and its efficiency over REST in terms of speed, memory, and
 payload size.
 
-Typically, data exchange over REST should be limited to short messages
-exchanged over JSON, whereas gRPC can handle large data transfer and
-even allows for bidirectional streaming.
-
-In general, it is preferable to choose gRPC over REST due to the
-performance benefits of a binary compatible protocol.  While REST
-carries a variety of benefits, for complex client/server interactions,
-it is best to have an interface that can efficiently exchange a wide
-variety of data formats and messages.
+Typically, REST data exchanges should be limited to short messages
+transferred via 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
+benefits of a binary compatible protocol. While REST provides a variety of
+benefits, for complex client/server interactions, it is best to have an
+interface that can efficiently exchange a wide variety of data formats and
+messages.
 
 
 .. _gRPC: https://grpc.io/

doc/source/abstraction/index.rst

@@ -5,11 +5,11 @@ of an application from the user and emphasizing only usage.
 
 One of the main objectives of PyAnsys libraries is to wrap (encapsulate) 
 data and methods within units of execution while hiding data or parameters 
-in protected variables. The topics in this section demonstrate how 
-applications and complex services expose functionalities that matter to 
-users and hide all else. For example, because background details, 
-implementation, and hidden states do not need to be exposed to users, 
-they are hidden.
+in protected variables.
+
+The topics in this section demonstrate how applications and complex services
+expose functionalities that matter to users and hide all else. For example,
+background details, implementation, and hidden states can all be hidden.
 
 .. toctree::
    :hidden:
@@ -18,4 +18,4 @@ they are hidden.
    app_interface_abstraction
    service_abstraction
    data_transfer_and_representation
-   
+   

doc/source/abstraction/service_abstraction.rst

@@ -72,7 +72,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 via 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``.