andy edits

Author: akaszynski

doc/source/abstraction/data_transfer_and_representation.rst

@@ -1,11 +1,13 @@
-Data Transfer and Representation
-================================
-When transferring data from a local application or remote service, you 
-do not want to return raw JSON, gRPC classes, Python lists, or, even worse, 
-strings. A best practice is to represent arrays as ``numpy.ndarray`` or
-``pandas.DataFrame`` objects.
+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.
 
-This example generates a simple mesh in MAPDL:
+For example, consider a simple mesh in MAPDL:
 
 .. code:: python
 
@@ -20,7 +22,7 @@ command or to write it to disk using the ``CDWRITE`` command. Both
 methods are remarkably inefficient, requiring:
 
 - Serializing the data to ASCII on the server
-- Transfering the data
+- Transferring the data
 - Deserializing the data within Python
 - Converting the data to an array
 
@@ -63,6 +65,49 @@ 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.
+
+
+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
+expose only a limited number of RPC methods in the front-facing API.
+
+Compatibility and Efficiency
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+APIs should be designed to be compatible with as many languages and
+platforms as possible.  `gRPC`_ for RPC-like interfaces should be one
+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.
+
+
 
 .. _gRPC: https://grpc.io/
 .. _pythoncom: http://timgolden.me.uk/pywin32-docs/pythoncom.html

doc/source/documentation/class_documentation.rst

@@ -40,7 +40,7 @@ parameters are automatically assigned to the class.
 Auto-Generated Documentation
 ----------------------------
 
-To automatically genereate class descriptions, use either the ``autoclass``  
+To automatically generate class descriptions, use either the ``autoclass``  
 or ``autosummary`` directive.
 
 For simple classes, you can use the ``autoclass`` directive::

doc/source/documentation/coding_style.rst

@@ -9,7 +9,7 @@ beyond `PEP8 <https://www.python.org/dev/peps/pep-0008/>`__.
 
 For example, `Stack Overflow Answer <https://stackoverflow.com/questions/2536307>`_ 
 outlines deprecation best practices and a `Deprecation library <https://deprecation.readthedocs.io/>`_ 
-aready exists. However, there is no official guidance regarding deprecating features 
+already exists. However, there is no official guidance regarding deprecating features 
 in an API within Python. This page seeks to clarify this issue and others.
 
 Aside from the following PyAnsys-specific directives, the best coding practice is to 

doc/source/documentation/docstrings.rst

@@ -15,7 +15,7 @@ documentation style. To use `numpydoc`_ add the following to your
 
 Minimum Requirements
 --------------------
-PyAnsys libary docstrings contain at a minimum the following
+PyAnsys library docstrings contain at a minimum the following
 `numpydoc`_ sections:
 
 * `Short description <https://numpydoc.readthedocs.io/en/latest/format.html#short-summary>`_.
@@ -25,7 +25,7 @@ PyAnsys libary docstrings contain at a minimum the following
 * `Examples <https://numpydoc.readthedocs.io/en/latest/format.html#examples>`_
 
 These sections should follow the numpydoc standards.  To avoid
-inconsistencies between PyAnsys libaries, adhere to the following
+inconsistencies between PyAnsys libraries, adhere to the following
 additional standards:
 
 
@@ -38,7 +38,7 @@ Always specify the type, and whenever necessary, provide the full class name::
   my_obj : :class:`ansys.<product>.<library>.FooClass`
       Description of FooClass.
   some_int : int
-      Some interger value.
+      Some integer value.
 
 .. note::
    These parameter descriptions have punctuation. 

doc/source/documentation/index.rst

@@ -1,3 +1,5 @@
+.. _api_documentation:
+
 API Documentation
 #################
 Good documentation drives library adoption and usage and is the
@@ -9,16 +11,16 @@ documentation or examples they are presented with.
 Good API documentation provides the following:
 
 * Increased adoption and improved experience for the developers using
-  the API or libary.
+  the API or library.
 * Reduction in the time spent on-boarding new users (both contributors
   and users of the project).
-* Better maintainance of the codebase.  The time spent reading the
+* Better maintenance of the code base.  The time spent reading the
   source is often orders of magnitude greater than the time spent
   writing it.  Well documented code (both in user-facing docstrings
-  and developer comments) pays dividends in code maintaince.
+  and developer comments) pays dividends in code maintenance.
 * Reduces the amount of time spent understanding the features API.
 
-The documentation for a PyAnsys libary should contain the following
+The documentation for a PyAnsys library should contain the following
 
 * Module, class, method, and function documentation strings.  See
   :ref:`docstrings`.

doc/source/images/diagram.png

@@ -22,13 +22,16 @@ This figure shows the general pattern that each PyAnsys library should follow:
 .. image:: ../images/diagram.png
   :alt: Overview Diagram
 
-The Ansys product or service exposes an interface that is locally accessible 
-(in the case of .NET using `pythoncom`_, `SWIG`_, or `C extensions`_) or a 
-service that is both locally and remotely accessible (`REST`_ or `gRPC`_). 
-This interface is referred to as the API (Application Programming Interface). 
-While this API can be directly accessed, this often results in unreadable 
-and unmaintainable code that forces users to rewrite setup boilerplate and 
-other methods from scratch.
+The Ansys product or service exposes an interface that is locally
+accessible (for example, .NET using `pythoncom`_, `SWIG`_, or `C
+extensions`_) or a service that is both locally and remotely
+accessible (`REST`_ or `gRPC`_).  This interface is referred to as the
+API (Application Programming Interface).  While this API can be
+directly accessed, this often results in unreadable and unmaintainable
+code that forces users to rewrite setup boilerplate and other methods
+from scratch.  Therefore, the best practice is to create a Python layer
+that maps the raw API into a carefully designed, object oriented data
+model and API.
 
 .. toctree::
    :hidden:
@@ -42,6 +45,7 @@ other methods from scratch.
    readme_file
    setup_file
    doc_directory  
+   license
 
 .. _gRPC: https://grpc.io/
 .. _pythoncom: http://timgolden.me.uk/pywin32-docs/pythoncom.html

doc/source/library_description/index.rst

@@ -0,0 +1,8 @@
+.. _license_file:
+
+License File
+############
+PyAnsys projects are expected to have this exact license included in
+the root directory of their project.
+
+.. include:: ../../LICENSE

doc/source/library_description/license.rst

@@ -1,3 +1,5 @@
+.. _setup_file:
+
 Setup File
 ##########
 The setup file for a PyAnsys library package, ``setup.py``, should contain 

doc/source/library_description/setup_file.rst

@@ -6,27 +6,48 @@ libraries requires that the relevant Ansys products are licensed
 either directly or indirectly, you can distribute your custom-made 
 applications and workflows internally or externally.
 
+
 Licensing and Approval
 ======================
-To allow for commerical use, a PyAnsys library must use the MIT 
-license. Because this license falls in the BSD-style license 
-class, you do not have to provide any source code when releasing 
-new software. To make your PyAnsys library suitable for commercial 
-use, you need only to include the original MIT license in the 
-reused code.
+To allow for commercial use, a PyAnsys library must use the MIT
+license. Because this license falls in the BSD-style license class,
+PyAnsys libraries can be used as a shared library with no
+restrictions.  This follows the pattern of including a PyAnsys as a
+dependency in ``install_requires`` in the ``setup.py``.
+
+Should you choose to copy and include any PyAnsys project source uses,
+all you have to do to to make your library suitable for commercial
+use, is to a copy of the original PyAnsys MIT license in the reused
+code.
 
 To view this license, see the `LICENSE` file in the root directory 
 of this repository. This file must be included in the root 
 directory of the repository for every PyAnsys library.
 
+
 Project Approval
 ================
-Exposing new Ansys technologies through the PyAnsys project is 
-subject to an internal review and decision process. Reach out 
-to Stephane Marguerin and Alexander Kaszynski for any requests.
+Exposing new Ansys technologies through the PyAnsys project is subject
+to an internal review and decision process. Please reach out to
+Stephane Marguerin or Alexander Kaszynski for any requests.
+
 
-Repository Management
-=====================
-(To Be Developed)
+Repository Management and Standards
+===================================
+Each PyAnsys repository should at the minimum be administrated by a
+single individual with "Admin" permissions over the repository.  This
+enables them to override any blocking pull requests or to change the
+settings for that repository (e.g. GitHub pages, repository
+description, managing branch protections).
 
+Each repository is expected to follow a minimum set of standards:
 
+- Minimum code standards following PEP8 and described in <REF Code
+  Guidelines Section>
+- CI/CD using GitHub actions or Azure Devops enforcing coding standards.
+- Publicly hosted documentation detailing API with examples.  See
+  :ref:`api_documentation`.
+- Unit testing with at least 80% test coverage.
+- Infrastructure in place to deploy the library as a package on `PyPi
+  <https://pypi.org/>`_
+- Proper license file and author (see :ref:`setup_file` and `ref:`license_file`)