From 308fc1603107276da3dcfcb990ee9f335c0f7057 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Wed, 6 Apr 2022 16:40:40 +0200 Subject: [PATCH 1/4] New doc/source/abstractions chapter --- .../app-interface.rst} | 5 +++-- .../data-transfer.rst} | 5 +++-- doc/source/abstractions/index.rst | 21 +++++++++++++++++++ .../service.rst} | 5 +++-- doc/source/guidelines/index.rst | 3 --- doc/source/index.rst | 1 + 6 files changed, 31 insertions(+), 9 deletions(-) rename doc/source/{guidelines/app_interface_abstraction.rst => abstractions/app-interface.rst} (98%) rename doc/source/{guidelines/data_transfer_and_representation.rst => abstractions/data-transfer.rst} (98%) create mode 100644 doc/source/abstractions/index.rst rename doc/source/{guidelines/service_abstraction.rst => abstractions/service.rst} (99%) diff --git a/doc/source/guidelines/app_interface_abstraction.rst b/doc/source/abstractions/app-interface.rst similarity index 98% rename from doc/source/guidelines/app_interface_abstraction.rst rename to doc/source/abstractions/app-interface.rst index 57398ac85..49ea287a0 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 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..9f901223a --- /dev/null +++ b/doc/source/abstractions/index.rst @@ -0,0 +1,21 @@ +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. For example, +background details, implementation, and hidden 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 From a7729368bcb5634983ce9252a9766e9f70ddbe4d Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Wed, 6 Apr 2022 17:17:13 +0200 Subject: [PATCH 2/4] Fix PyAEDT link --- doc/source/abstractions/app-interface.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/abstractions/app-interface.rst b/doc/source/abstractions/app-interface.rst index 49ea287a0..3625e1ac6 100644 --- a/doc/source/abstractions/app-interface.rst +++ b/doc/source/abstractions/app-interface.rst @@ -55,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. @@ -109,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 From 7f31efd4cfe2c9f882a8d4ec91200d4e6b30b348 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Wed, 6 Apr 2022 17:21:21 +0200 Subject: [PATCH 3/4] Fix app-interface.rst table header --- doc/source/abstractions/app-interface.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/abstractions/app-interface.rst b/doc/source/abstractions/app-interface.rst index 3625e1ac6..d5a718743 100644 --- a/doc/source/abstractions/app-interface.rst +++ b/doc/source/abstractions/app-interface.rst @@ -15,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 | From 85cfdc4a7436a643648e90c38aca392fd4017e29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Mart=C3=ADnez?= <28702884+jorgepiloto@users.noreply.github.com> Date: Thu, 7 Apr 2022 15:58:47 +0200 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Maxime Rey <87315832+MaxJPRey@users.noreply.github.com> --- doc/source/abstractions/index.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/abstractions/index.rst b/doc/source/abstractions/index.rst index 9f901223a..bdddd675f 100644 --- a/doc/source/abstractions/index.rst +++ b/doc/source/abstractions/index.rst @@ -9,8 +9,9 @@ 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, -background details, implementation, and hidden states can all be hidden. +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: