ENH: restore abstractions chapter (#74)

* New doc/source/abstractions chapter

* Fix PyAEDT link

* Fix app-interface.rst table header

* Apply suggestions from code review

Co-authored-by: Maxime Rey <[email protected]>

Co-authored-by: Maxime Rey <[email protected]>

Author: jorgepiloto

doc/source/guidelines/app_interface_abstraction.rst renamed to doc/source/abstractions/app-interface.rst

@@ -1,5 +1,6 @@
-Application Interface Abstraction
-=================================
+Application Interface
+=====================
+
 Many Ansys applications are designed around user interaction within a
 desktop GUI-based environment. Consequently, scripts are recorded
 directly from user sessions and are in the context of manipulating the
@@ -14,7 +15,7 @@ open region in the active editor:
 
 +------------------------------------------------------+----------------------------------------------+
 | Using a Recorded Script from AEDT (MS COM Methods)   | Using the `PyAEDT`_ Library                  |
-+------------------------------------------------------+----------------------------------------------+
++======================================================+==============================================+
 | .. code:: python                                     | .. code:: python                             |
 |                                                      |                                              |
 |    import sys                                        |    from pyaedt import Hfss                   |
@@ -54,7 +55,7 @@ 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.
 
-The source of the ``hfss.py`` method within`PyAEDT`_ follows. 
+The source of the ``hfss.py`` method within `PyAEDT`_ follows. 
 Note how calls to the COM object are all encapsulated 
 within this method.
 
@@ -108,5 +109,5 @@ 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
+.. _PyAEDT: https://github.com/pyansys/pyaedt
 .. _Style Guide for Python Code (PEP8): https://www.python.org/dev/peps/pep-0008

doc/source/guidelines/data_transfer_and_representation.rst renamed to doc/source/abstractions/data-transfer.rst

@@ -1,5 +1,6 @@
-Data Transfer and Abstraction
-=============================
+Data Transfer
+=============
+
 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 files, gRPC messages, SWIG objects,

doc/source/abstractions/index.rst

@@ -0,0 +1,22 @@
+Abstractions
+############
+
+Abstraction in Python is the process of hiding the real implementation
+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, such as conditional
+statements and algorithms. For example, background details, implementation,
+and states can all be hidden.
+
+.. toctree::
+   :hidden:
+   :maxdepth: 3
+
+   app-interface
+   data-transfer
+   service

doc/source/guidelines/service_abstraction.rst renamed to doc/source/abstractions/service.rst

@@ -1,5 +1,6 @@
-Service Abstraction
-===================
+Service
+=======
+
 Some Ansys products are exposed as services that permit remote
 execution using technologies like `REST`_ or `gRPC`_.  These services
 are typically exposed in a manner where the API has already been

doc/source/guidelines/index.rst

@@ -13,9 +13,6 @@ functionalities such as logging, data transfer, and application APIs.
    dev_practices
    version_support
    doc_practices
-   app_interface_abstraction
-   data_transfer_and_representation
    logging
-   service_abstraction
    test_practices
    private_packaging

doc/source/index.rst

@@ -12,3 +12,4 @@
    packaging/index
    coding_style/index
    documentation_style/index
+   abstractions/index