diff --git a/doc/source/guidelines/app_interface_abstraction.rst b/doc/source/abstractions/app-interface.rst similarity index 95% rename from doc/source/guidelines/app_interface_abstraction.rst rename to doc/source/abstractions/app-interface.rst index 57398ac85..d5a718743 100644 --- a/doc/source/guidelines/app_interface_abstraction.rst +++ b/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 diff --git a/doc/source/guidelines/data_transfer_and_representation.rst b/doc/source/abstractions/data-transfer.rst similarity index 98% rename from doc/source/guidelines/data_transfer_and_representation.rst rename to doc/source/abstractions/data-transfer.rst index 57701c07a..66a15e148 100644 --- a/doc/source/guidelines/data_transfer_and_representation.rst +++ b/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, diff --git a/doc/source/abstractions/index.rst b/doc/source/abstractions/index.rst new file mode 100644 index 000000000..bdddd675f --- /dev/null +++ b/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 diff --git a/doc/source/guidelines/service_abstraction.rst b/doc/source/abstractions/service.rst similarity index 99% rename from doc/source/guidelines/service_abstraction.rst rename to doc/source/abstractions/service.rst index 14a937a06..fd250d57a 100644 --- a/doc/source/guidelines/service_abstraction.rst +++ b/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 diff --git a/doc/source/guidelines/index.rst b/doc/source/guidelines/index.rst index 19fdb626e..d9dd95bc8 100644 --- a/doc/source/guidelines/index.rst +++ b/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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 45d34af8a..81b182d26 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -12,3 +12,4 @@ packaging/index coding_style/index documentation_style/index + abstractions/index