From 9df1ced9a9483a0c48647047b0acf7ce6a723e44 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 14:28:00 -0400 Subject: [PATCH 01/56] Update README.rst --- README.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index 7c831680b..ebab2254d 100644 --- a/README.rst +++ b/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 `_. 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. From 4234d62949f9e9ce017d2a17b2e4c9b3b368c16a Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 14:44:33 -0400 Subject: [PATCH 02/56] Update app_interface_abstraction.rst --- doc/source/abstraction/app_interface_abstraction.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/abstraction/app_interface_abstraction.rst b/doc/source/abstraction/app_interface_abstraction.rst index a03437796..408773b7c 100644 --- a/doc/source/abstraction/app_interface_abstraction.rst +++ b/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 \ No newline at end of file +.. _Style Guide for Python Code (PEP8): https://www.python.org/dev/peps/pep-0008 From c0fb44f56d29c9422798468d7a0b26a88973b3c3 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 15:07:33 -0400 Subject: [PATCH 03/56] Update data_transfer_and_representation.rst --- .../data_transfer_and_representation.rst | 63 +++++++++---------- 1 file changed, 31 insertions(+), 32 deletions(-) diff --git a/doc/source/abstraction/data_transfer_and_representation.rst b/doc/source/abstraction/data_transfer_and_representation.rst index e7d950d68..b9f6adf98 100644 --- a/doc/source/abstraction/data_transfer_and_representation.rst +++ b/doc/source/abstraction/data_transfer_and_representation.rst @@ -3,9 +3,9 @@ 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 +.NET objects. Rather, it preferably returns standard Python objects like lists, strings, dictionaries when useful, and NumPy arrays or -pandas dataframes for more complex data. +Pandas 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/ From c6baee2d2369aafce3e433051b03550beea6adde Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 15:14:24 -0400 Subject: [PATCH 04/56] Update index.rst --- doc/source/abstraction/index.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/abstraction/index.rst b/doc/source/abstraction/index.rst index a5b1d2ec4..f8692c112 100644 --- a/doc/source/abstraction/index.rst +++ b/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 - \ No newline at end of file + From 398264e6819bfe0d05d4209d03c685955d8935cb Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 15:17:06 -0400 Subject: [PATCH 05/56] Update service_abstraction.rst --- doc/source/abstraction/service_abstraction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/abstraction/service_abstraction.rst b/doc/source/abstraction/service_abstraction.rst index afa23b0af..14a937a06 100644 --- a/doc/source/abstraction/service_abstraction.rst +++ b/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``. From 7bdc64335be2e2cb05a3090b3c1495ff4599c9b9 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 15:20:49 -0400 Subject: [PATCH 06/56] Update best_practices.rst --- doc/source/coding_style/best_practices.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/coding_style/best_practices.rst b/doc/source/coding_style/best_practices.rst index 7665afa42..b09ca6e7c 100644 --- a/doc/source/coding_style/best_practices.rst +++ b/doc/source/coding_style/best_practices.rst @@ -1,10 +1,10 @@ .. _best-practices: -Best-Practices +Best Practices ============== The following sections summarize the key points from `PEP8`_ and how -they apply to PyAnsys libaries. The PyAnsys libraries will -attempt to be consistent in style and formatting with the "big three" +they apply to PyAnsys libaries. The goal is for PyAnsys libraries to +be consistent in style and formatting with the "big three" data science libraries: `NumPy`_, `SciPy`_, and `pandas`_. .. _NumPy: https://numpy.org/ From da9002c347866c050ccb12c31957eda3b4f83da0 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 15:29:51 -0400 Subject: [PATCH 07/56] Update data_transfer_and_representation.rst --- .../abstraction/data_transfer_and_representation.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/abstraction/data_transfer_and_representation.rst b/doc/source/abstraction/data_transfer_and_representation.rst index b9f6adf98..57701c07a 100644 --- a/doc/source/abstraction/data_transfer_and_representation.rst +++ b/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 preferably returns 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 `_ +arrays or `pandas `_ dataframes for more complex data. For example, consider a simple mesh in MAPDL: From a491601f2b9dd4cc0d4a306413e3ddc5e40c51ce Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 16:07:35 -0400 Subject: [PATCH 08/56] Update best_practices.rst --- doc/source/coding_style/best_practices.rst | 121 ++++++++++----------- 1 file changed, 60 insertions(+), 61 deletions(-) diff --git a/doc/source/coding_style/best_practices.rst b/doc/source/coding_style/best_practices.rst index b09ca6e7c..c4672fbb7 100644 --- a/doc/source/coding_style/best_practices.rst +++ b/doc/source/coding_style/best_practices.rst @@ -22,7 +22,7 @@ might only be discovered during runtime. .. _ImportError: https://docs.python.org/3/library/exceptions.html#ImportError -Avoid this: +Avoid: .. code:: python @@ -30,7 +30,7 @@ Avoid this: import math return math.log(8, x) -Instead: +Use: .. code:: python @@ -98,7 +98,7 @@ Use: return math.log(8, x) -You should generally avoid using wild cards in imports because doing so +You should avoid using wild cards in imports because doing so can cause confusion on which names are present in the namespaces. Avoid: @@ -107,7 +107,7 @@ Avoid: from my_package.mymodule import * -Instead: +Use: .. code:: python @@ -120,11 +120,11 @@ Proper and consistent indentation is important to producing easy-to-read and maintainable code. In Python, use four spaces per indentation level and avoid tabs. -Indentation should be used to: +Indentation should be used to emphasize: - - Emphasize the body of a control statement, such as a loop or a select statement. - - Emphasize the body of a conditional statement. - - Emphasize a new scope block. + - Body of a control statement, such as a loop or a select statement + - Body of a conditional statement + - New scope block .. code:: python @@ -139,7 +139,8 @@ Indentation should be used to: return For improved readability, add blank lines or wrapping lines. Two -blank lines should be added before and after all function and class definitions. +blank lines should be added before and after all function and class +definitions. Inside a class, use a single line before any method definition. @@ -156,7 +157,8 @@ Inside a class, use a single line before any method definition. """Second method docstring""" return -Use a blank line to separate logical sections. +To make it clear when a "paragraph" of code is complete and a new section +is starting, use a blank line to separate logical sections. Instead of: @@ -198,18 +200,15 @@ Use: print("x is less than zero.") -This way, it's clear when a "paragraph" of code is complete and -a new section is starting. - - Maximum Line Length ------------------- For source code lines, best practice is to keep the length at or below -100 characters. For docstrings and comments, best practice is to keep +100 characters. For docstrings and comments, best practice is to keep the length at or below 72 characters. -Lines longer than this might not display properly on some terminals and tools -or might be difficult to follow. For example, this line is difficult to follow: +Lines longer than these recommended limits might not display properly +on some terminals and tools or might be difficult to follow. For example, +this line is difficult to follow: .. code:: python @@ -251,12 +250,12 @@ indistinguishable from the numerals one and zero. Package and Module Naming Conventions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use a short, lowercase word or words for module names. Separate words -with underscores to improve readability. For example, ``module.py`` or -``my_module.py``. +with underscores to improve readability. For example, use ``module.py`` +or ``my_module.py``. -For a package name, use a short, lowercase word or words. Avoid -underscores as these will have to be represented as dashes when -installing from PyPi. +For a package name, use a short, lowercase word or words. Avoid +underscores as these must be represented as dashes when installing +from PyPi. .. code:: @@ -265,8 +264,8 @@ installing from PyPi. Class Naming Conventions ~~~~~~~~~~~~~~~~~~~~~~~~ -Use camel case when naming classes. Do not separate words -with underscores. For example: +Use camel case when naming classes. Do not separate words +with underscores. .. code:: python @@ -339,9 +338,9 @@ readability. Comments -------- -Because PyAnsys projects generally involve multiple physics domains, +Because a PyAnsys library generally involve multiple physics domains, users reading its source code do not have the same background as -the person who writes it. This is why it is important for this library +the developers who wrote it. This is why it is important for a library to have well commented and documented source code. Comments that contradict the code are worse than no comments. Always make a priority of keeping comments up to date with the code. @@ -363,20 +362,20 @@ Here are general guidelines for writing comments: #. Warn of consequences. Obvious portions of the source code should not be commented. -For example: +For example, the following comment is not needed: .. code:: python # increment the counter i += 1 -However, important portions of the behavior that are not self-apparent -should include a note from the developer writing it. Otherwise, -future developers may remove what they see as unnecessary. For example: +However, an important portion of the behavior that is not self-apparent +should include a note from the developer writing it. Otherwise, +future developers may remove what they see as unnecessary. .. code:: python - # Be sure to reset the object's cache prior to exporting, otherwise + # Be sure to reset the object's cache prior to exporting. Otherwise, # some portions of the database in memory will not be written. obj.update_cache() obj.write(filename) @@ -384,27 +383,27 @@ future developers may remove what they see as unnecessary. For example: Inline Comments ~~~~~~~~~~~~~~~ -Inline comments should be used sparingly. An inline comment is a comment -on the same line as a statement. +Use inline comments sparingly. An inline comment is a comment on the +same line as a statement. Inline comments should be separated by two spaces from the statement. -For example: .. code:: python x = 5 # This is an inline comment -Inline comments that state the obvious are distracting. Again, avoid: +Inline comments that state the obvious are distracting and should be +avoided: .. code:: python x = x + 1 # Increment x -Focus on writing self-documenting code and using short, but +Focus on writing self-documenting code and using short but descriptive variable names. -Rather than: +Avoid: .. code:: python @@ -420,7 +419,7 @@ Use: Documentation Convention ------------------------ A docstring is a string literal that occurs as the first statement in -a module, function, class, or method definition. A docstring becomes +a module, function, class, or method definition. A docstring becomes the doc special attribute of the object. Write docstrings for all public modules, functions, classes, and @@ -431,7 +430,7 @@ To create a docstring, surround the comments with three double quotes on either side. For a one-line docstring, keep both the starting and ending ``"""`` on the -same line. For example: +same line. .. code:: python @@ -450,9 +449,9 @@ source projects. For a full description of the code style, reference Programming Recommendations --------------------------- -This section provides some of the `PEP8 +This section provides some `PEP8 `_ suggestions for removing -ambiguity and preserving consistency. They address some common pitfalls +ambiguity and preserving consistency. They address some common pitfalls when writing Python code. @@ -461,7 +460,7 @@ Booleans and Comparisons Don't compare Boolean values to ``True`` or ``False`` using the equivalence operator. -Rather than: +Avoid: .. code:: python @@ -479,7 +478,7 @@ Knowing that empty sequences are evaluated to ``False``, don't compare the length of these objects but rather consider how they would evaluate by using ``bool()``. - Avoid: +Avoid: .. code:: python @@ -487,7 +486,7 @@ by using ``bool()``. if not len(my_list): raise ValueError('List is empty') -Instead: +Use: .. code:: python @@ -497,7 +496,7 @@ Instead: In ``if`` statements, use ``is not`` rather than ``not ...``. -Rather than: +Avoid: .. code:: python @@ -519,7 +518,7 @@ Handling Strings ~~~~~~~~~~~~~~~~ Use ``.startswith()`` and ``.endswith()`` instead of slicing. -Rather than: +Avoid: .. code:: python @@ -563,8 +562,8 @@ Duplicated Code ~~~~~~~~~~~~~~~ Follow the DRY principle, which states that "Every piece of knowledge must have a single, unambiguous, authoritative representation within a -system." Attempt to follow this unless it overly complicates the code. -For instance, the following example converts Fahrenheit to Celsius +system." Attempt to follow this principle unless it overly complicates +the code. For instance, the following example converts Fahrenheit to kelvin twice, which now requires the developer to maintain two separate lines that do the same thing. @@ -576,7 +575,7 @@ that do the same thing. temp2 = 46 new_temp_k = ((temp2 - 32) * (5 / 9)) + 273.15 -Instead, write a simple method that converts Fahrenheit to Celsius: +Instead, write a simple method that converts Fahrenheit to kelvin: .. code:: python @@ -595,7 +594,7 @@ Instead, write a simple method that converts Fahrenheit to Celsius: """ return ((fahr - 32) * (5 / 9)) + 273.15 -Now, you can execute and get the exact same output with: +Now, you can execute and get the same output with: .. code:: python @@ -603,9 +602,9 @@ Now, you can execute and get the exact same output with: new_temp_k = fahr_to_kelvin(46) This is a trivial example, but the approach can be applied for a -variety of both simple and complex algorithms and workflows. Another -advantage of this approach is that you can now implement unit testing -for this method. For example: +variety of both simple and complex algorithms and workflows. Another +advantage of this approach is that you can implement unit testing +for this method. .. code:: python @@ -615,7 +614,7 @@ for this method. For example: assert np.isclose(12.7778, fahr_to_kelvin(55)) Now, not only do you have one line of code to verify, but using a -testing framework such as ``pytest``, you can verify that the method is +testing framework such as ``pytest``, you can test that the method is correct. @@ -623,7 +622,7 @@ Nested Blocks ~~~~~~~~~~~~~ Avoid deeply nested block structures (such as conditional blocks and loops) -within one single code block. For example: +within one single code block. .. code:: python @@ -645,7 +644,8 @@ within one single code block. For example: Aside from the lack of comments, this complex nested validation method is difficult to debug and validate with unit testing. It would -be far better to implement more validation methods and join conditionals. +be far better to implement more validation methods and join conditional +blocks. For a conditional block, the maximum depth recommended is four. If you think you need more for the algorithm, create small functions that are @@ -680,7 +680,7 @@ Implement a list comprehension with: If the loop is too complicated for creating a list comprehension, -consider creating small functions and calling these instead. For +consider creating small functions and calling these instead. For example, extract all consonants in a sentence: .. code:: python @@ -699,7 +699,7 @@ This is better implemented by creating a simple method to return if a letter is a consonant. >>> def is_consonant(letter): - ... """Return True when a letter is a consonant.""" + ... """Return ``True`` when a letter is a consonant.""" ... vowels = 'aeiou' ... return letter.isalpha() and letter.lower() not in vowels ... @@ -708,6 +708,5 @@ letter is a consonant. >>> consonants ['T', 'h', 's', 's', 's', 'm', 'p', 'l', 's', 'n', 't', 'n', 'c'] -The advantage of the second approach is it is more readable and better -documented. Additionally, while it's a trivial example, you could -implement a unit test for ``is_consonant``. +The second approach is more readable and better documented. Additionally, +you could implement a unit test for ``is_consonant``. From 924864e371b6a2d3d02e73a449bc25ade75806d5 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 16:29:41 -0400 Subject: [PATCH 09/56] Create best_practices.rst --- doc/source/coding_style/best_practices.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/source/coding_style/best_practices.rst b/doc/source/coding_style/best_practices.rst index c4672fbb7..77c9c5e75 100644 --- a/doc/source/coding_style/best_practices.rst +++ b/doc/source/coding_style/best_practices.rst @@ -613,14 +613,13 @@ for this method. def test_fahr_to_kelvin(): assert np.isclose(12.7778, fahr_to_kelvin(55)) -Now, not only do you have one line of code to verify, but using a -testing framework such as ``pytest``, you can test that the method is +Now, not only do you have one line of code to verify, but you can also +use a testing framework such as ``pytest`` to test that the method is correct. Nested Blocks ~~~~~~~~~~~~~ - Avoid deeply nested block structures (such as conditional blocks and loops) within one single code block. From f7aa4731c71f1ee277ffe1633aad31a60868f279 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 16:57:56 -0400 Subject: [PATCH 10/56] Update flake8.rst --- doc/source/coding_style/flake8.rst | 61 +++++++++++++++--------------- 1 file changed, 30 insertions(+), 31 deletions(-) diff --git a/doc/source/coding_style/flake8.rst b/doc/source/coding_style/flake8.rst index dbbfa5ffd..50bc8bd5c 100644 --- a/doc/source/coding_style/flake8.rst +++ b/doc/source/coding_style/flake8.rst @@ -2,37 +2,36 @@ Style Guide Enforcement ======================= -The following sections will describe the use of flake8 for `PEP8`_ style -enforcement and the minimum standards expected. The PyAnsys libraries -will be consistent with these basic guidelines. +The following sections describe the use of flake8 for `PEP8`_ style +enforcement and the minimum standards expected. PyAnsys libraries +are to be consistent with these guidelines. .. _PEP8: https://www.python.org/dev/peps/pep-0008/ Flake8 ~~~~~~ -`Flake8`_ is a python tool for enforcing code styling. It is a wrapper +`Flake8`_ is a Python tool for enforcing code styling. It is a wrapper around the following three tools: `PyFlakes`_, `pycodestyle`_, and `Ned Batchelder's McCabe script for complexity`_. Flake8 runs all three tools at once, checking the code against a variety of style rules, such as line length, -code complexity, whitespace, etc. +code complexity, and whitespace. .. _Flake8: https://flake8.pycqa.org/en/latest/index.html .. _PyFlakes: https://pypi.org/project/pyflakes/ .. _pycodestyle: https://pypi.org/project/pycodestyle/ .. _`Ned Batchelder's McCabe script for complexity`: https://github.com/PyCQA/mccabe - .. _configuring-flake8: Configuring Flake8 ------------------ Flake8 supports configuring a specific set of style rules to -enforce. This configuration can be stored in your project in a -``setup.cfg``, ``tox.ini``, or ``.flake8`` file. The PyAnsys libraries +enforce. This configuration can be stored in your library in a +``setup.cfg``, ``tox.ini``, or ``.flake8`` file. PyAnsys libraries store the flake8 configuration in a ``.flake8`` file at the root of the repository. -Here is an example of a ``.flake8`` configuration file from one of the -PyAnsys libraries: +Here is an example of a ``.flake8`` configuration file from a PyAnsys +library: .. code:: @@ -69,8 +68,9 @@ The above configuration defines the following options: - ``max-line-length`` This denotes the maximum line length for any one line of code. - The `PEP8`_ standard advises a line length of 79. Since this is a bit - limiting in some cases, a maximum line length of 100 is suggested. + The `PEP8`_ standard advises a maximum line length of 79. Because + this is a bit limiting in some cases, the maximum line length + recommended for a PyAnsys libary is 100. - ``statistics`` This enables the number of occurrences of each error or warning code @@ -91,45 +91,44 @@ Then, flake8 can be run from inside your project directory by executing: flake8 . -This will use the configuration defined in the ``.flake8`` file to +This uses the configuration defined in the ``.flake8`` file to run the style checks on the appropriate files within the project and report any errors. In PyAnsys libraries, flake8 is run as part of the CI/CD for code style. This action is run as a required check on pull requests, preventing -code in violation of these style rules from being merged into the code +code in violation of style rules from being merged into the code base. Utilizing Black ~~~~~~~~~~~~~~~ Manually checking for code styling can be a tedious task. Luckily, -there are several python tools for autoformatting code to meet PEP8 -standards to help with this. The PyAnsys project suggests the use of the +several Python tools for autoformatting code to meet PEP8 standards +are available to help with this. The PyAnsys project suggests the use of the the formatting tool `black`_. - -Upon completing a code change, and before committing, `black`_ can be +On completing a code change, and before committing, `black`_ can be run to reformat the code, following the PEP8 guidelines enforced through flake8. This will limit any manual code changes needed to address style rules. .. _black: https://black.readthedocs.io/en/stable/ -Optionally, it is possible to automate the use of ``black`` as well. -This can be done with the tool `pre-commit`_. Setting up a `pre-commit hook +Optionally, it is possible to automate the use of ``black``. This can be +done with the tool `pre-commit`_. Setting up a `pre-commit hook to run black `_ -will automatically format the code before committing. This is the -simplest way to incorporate code style checks into the development -workflow with the least amount of manual effort to maintain PEP8 guidelines. +will automatically format the code before committing. This simple way of +incorporating code style checks into the development workflow to maintain +PEP8 guidelines requires mininmal manual effort. .. _pre-commit: https://pre-commit.com/ Minimum Standards ~~~~~~~~~~~~~~~~~ -The following section describes the minimum set of code style standards -expected in an PyAnsys library. +Descriptions follow of the code style standards expected in the minimum set +for a PyAnsys library. * `W191`_ - **Indentation contains tabs.** @@ -180,7 +179,7 @@ expected in an PyAnsys library. * `E231`_ - **Missing whitespace after certain special characters.** - There should be one space after the characters ``,``, ``;``, or ``:``. + There should be one space after the characters ``,``, ``;``, and ``:``. * `E301`_ - **Expected a blank line, found none.** @@ -196,7 +195,7 @@ expected in an PyAnsys library. All code lines should not exceed 100 characters. The `PEP8 line length `_ guidelines suggest a maximum line length of 79. Following this limit - is not as necessary due to modern screen sizes. The suggested maximum + is not as necessary today due to modern screen sizes. The suggested maximum length of 100 can be easier to accommodate and can still support viewing files side-by-side in code editors. @@ -208,15 +207,15 @@ expected in an PyAnsys library. Importing everything from a module should never be done. Importing modules this way leads to uncertainty and pollutes the code. You - cannot know exactly what is being imported and it can often lead to - name clashes. It is best to import the exact modules to be used. + cannot know exactly what is being imported and name clashes are common. + Import only the modules to be used. * **Limit complexity of code to 10.** This is enforced by the ``max-complexity`` option described in :ref:`configuring-flake8`. Limiting code complexity leads to code that - is easier to understand and less risky to modify. Writing low - complexity code when possible is preferred. + is easier to understand and less risky to modify. Write low- + complexity code when possible. Your ``.flake8`` file should be: From defb178270e48e73822d1c4c59d910eb250b5199 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 16:58:57 -0400 Subject: [PATCH 11/56] Update index.rst --- doc/source/coding_style/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/coding_style/index.rst b/doc/source/coding_style/index.rst index 652fd2cf2..d2ec3e0af 100644 --- a/doc/source/coding_style/index.rst +++ b/doc/source/coding_style/index.rst @@ -3,8 +3,8 @@ Coding Style ************ -The PyAnsys libraries are expected to follow `PEP8`_ will -attempt to be consistent in style and formatting with the "big three" +PyAnsys libraries are expected to follow `PEP8`_ and +be consistent in style and formatting with the "big three" data science libraries: `NumPy`_, `SciPy`_, and `pandas`_. .. _NumPy: https://numpy.org/ From 21da844dec8a0fc5c1e1b323147b579faf6f6e4b Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:04:29 -0400 Subject: [PATCH 12/56] Update class_documentation.rst --- .../documentation_style/class_documentation.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/source/documentation_style/class_documentation.rst b/doc/source/documentation_style/class_documentation.rst index 2ca7bee00..fb7852d58 100644 --- a/doc/source/documentation_style/class_documentation.rst +++ b/doc/source/documentation_style/class_documentation.rst @@ -4,14 +4,14 @@ Class Documentation There are two main ways of using Sphinx to document an API class: * Manually describe "how" and "why" to use a class in either - a "User Guide" or an example within the library's documentation . + a "User Guide" or an example within the library's documentation * Automatically generate API documentation for classes using the - ``autoclass`` or ``autosummary`` directive. + ``autoclass`` or ``autosummary`` directive Manual Documentation -------------------- -To manually describe the "how" and "why" usage of a class, use the +To manually describe "how" and "why" to exercise a class, use the ``.. code:: python`` directive:: Initialize ``my_module.MyClass`` with initial parameters. These @@ -24,7 +24,7 @@ To manually describe the "how" and "why" usage of a class, use the >>> my_obj.parm1 'apple' -This will be rendered as: +This is rendered as: Initialize ``my_module.MyClass`` with initial parameters. These parameters are automatically assigned to the class. @@ -43,18 +43,18 @@ Auto-Generated Documentation To automatically generate class descriptions, use either the ``autoclass`` or ``autosummary`` directive. -For simple classes, you can use the ``autoclass`` directive:: +For simple classes, use the ``autoclass`` directive:: .. autoclass:: pyansys_sphinx_theme.samples.ExampleClass :members: -Which is rendered as: +This is rendered as: .. autoclass:: pyansys_sphinx_theme.samples.ExampleClass :members: -For complex classes with many methods, you should use -the ``autosummary`` directive:: +For complex classes with many methods, use the +``autosummary`` directive:: .. autoclass:: pyansys_sphinx_theme.samples.Complex From 6809415f252946c2c8fe2f54372bd35cadde901f Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:14:24 -0400 Subject: [PATCH 13/56] Update coding_style.rst --- doc/source/documentation_style/coding_style.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/documentation_style/coding_style.rst b/doc/source/documentation_style/coding_style.rst index 30c43d747..a6093711f 100644 --- a/doc/source/documentation_style/coding_style.rst +++ b/doc/source/documentation_style/coding_style.rst @@ -75,7 +75,7 @@ This example raises an ``Exception``: """ raise Exception('`my_function` has been deprecated.') -Because there is no built-in depreciation error within +Because there is no built-in deprecation error within Python, an alternative is to create a custom ``DeprecationError``. .. code:: python @@ -107,7 +107,7 @@ According to `Semantic Versioning `_, you should increment the MAJOR version when you make incompatible changes. However, adding or eliminating methods should not be considered incompatible changes to a code base but rather incremental changes -that are backwards-compatible (to a degree). Therefore, whenever a +that are backwards-compatible (to a degree). Therefore, whenever a method or feature is added, changed, or removed, the minor version should be bumped. @@ -154,7 +154,7 @@ First, install ``pytest``. pip install pytest -Now, run ``doctest`` can on any Python file. +Now, run ``doctest`` on any Python file. .. code:: From 301300de2b547d431551137a9a285dd16f66e69e Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:25:45 -0400 Subject: [PATCH 14/56] Update docstrings.rst --- doc/source/documentation_style/docstrings.rst | 31 ++++++++++--------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/doc/source/documentation_style/docstrings.rst b/doc/source/documentation_style/docstrings.rst index b1f38dec6..a148efaae 100644 --- a/doc/source/documentation_style/docstrings.rst +++ b/doc/source/documentation_style/docstrings.rst @@ -3,7 +3,7 @@ Docstring Standards ################### When writing docstrings for PyAnsys libraries, use the `numpydoc`_ -documentation style. To use `numpydoc`_ add the following to your +documentation style. To use `numpydoc`_, add the following to your ``conf.py``: .. code:: python @@ -19,14 +19,14 @@ PyAnsys library docstrings contain at a minimum the following `numpydoc`_ sections: * `Short description `_. -* `Extended Summary `_ (if applicable) +* `Extended Summary `_ if applicable * `Parameters `_ if applicable * `Returns `_ if applicable * `Examples `_ -These sections should follow the numpydoc standards. To avoid -inconsistencies between PyAnsys libraries, adhere to the following -additional standards: +These sections should follow the numpydoc standards. To avoid +inconsistencies between PyAnsys libraries, adhere to the additional +standards that follow. Parameters @@ -41,12 +41,15 @@ Always specify the type, and whenever necessary, provide the full class name:: Some integer value. .. note:: - These parameter descriptions have punctuation. + Parameter descriptions have punctuation. While the brief description itself + need not be a sentence, any text following it should a clear, complete + sentence. Returns ~~~~~~~ -Returns section contains only the return type and no the name and type:: +The Returns section contains only the return type and (not the name and type) +and a brief description:: Returns ------- @@ -55,7 +58,7 @@ Returns section contains only the return type and no the name and type:: Example Docstrings ------------------ -Methods and functions should generally be documented with the +Methods and functions should generally be documented within the ``Examples`` docstring section to make the usage of the method or function clear. Here is a sample function: @@ -75,7 +78,7 @@ This directive renders the sample function as: Validation ---------- -Enable validation of docstrings during the sphinx build by adding the +Enable validation of docstrings during the Sphinx build by adding the following line to ``conf.py``:: numpydoc_validation_checks = {"GL08"} @@ -84,17 +87,17 @@ This will issue the following warning for any objects without a docstring:: "The object does not have a docstring" -The ``"GL08"`` code is required at minimum for PyAnsys projects. -Other codes may be enforced at a later date; for a full listing see +The ``"GL08"`` code is required at minimum for PyAnsys libraries. +Other codes may be enforced at a later date. For a full listing, see `numpydoc Validation Check `_. Additional Information ---------------------- -Additional examples and notes can be found at `numpydoc`_. Reference -their documentation as the primary source of information regarding -docstring styles aside from the directives noted here. +Additional examples and notes can be found at `numpydoc`_. Reference +this documentation as the primary source of information regarding +docstring styles for directives not covered here. .. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html .. _googledoc: https://google.github.io/styleguide/ From db80c51317125dc0a8e110b5add87e9789aae146 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:32:02 -0400 Subject: [PATCH 15/56] Update index.rst --- doc/source/documentation_style/index.rst | 26 ++++++++++++------------ 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/source/documentation_style/index.rst b/doc/source/documentation_style/index.rst index 7ec21e71a..a0544012d 100644 --- a/doc/source/documentation_style/index.rst +++ b/doc/source/documentation_style/index.rst @@ -5,29 +5,29 @@ Documentation Style Good documentation drives library adoption and usage and is the foundation for a good developer experience. Even with the best interfaces and the most functional product, no one will adopt the API -if they don't know how to use it or if they aren't convinced by the +if they don't know how to use it or if they aren't satisifed with the documentation or examples they are presented with. -Good API documentation provides the following: +Good API documentation provides: -* Increased adoption and improved experience for the developers using +* Increased adoption and improved experiences for developers using the API or library. -* Reduction in the time spent on-boarding new users (both contributors - and users of the project). -* Better maintenance of the code base. The time spent reading the +* Reduction in the time spent on-boarding new contributors and users + of the library. +* 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 + writing it. Well documented code (both in user-facing docstrings and developer comments) pays dividends in code maintenance. -* Reduces the amount of time spent understanding the features API. +* Reduction in the amount of time spent understanding the API features. -The documentation for a PyAnsys library should contain the following +The documentation for a PyAnsys library should contain: -* Module, class, method, and function documentation strings. See +* Module, class, method, and function documentation strings. See :ref:`docstrings`. -* Full examples gallery. See `PyMAPDL Examples +* Full gallery of examples. See `PyMAPDL Examples `_ -* User guide. -* Link to this contributing guide. +* User guide for the library. +* Link to this developer's guide. .. toctree:: :hidden: From 0759cecfdf33cc11eea7a93959ea37d5d4e333a6 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:33:03 -0400 Subject: [PATCH 16/56] Update sample_func.py --- doc/source/documentation_style/sample_func.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/documentation_style/sample_func.py b/doc/source/documentation_style/sample_func.py index e9d06ba56..48412bcc9 100644 --- a/doc/source/documentation_style/sample_func.py +++ b/doc/source/documentation_style/sample_func.py @@ -7,9 +7,9 @@ def func(arg1, arg2): .. warning:: Use the ``.. warning::`` directive within the docstring for any - warnings that need to be explicitly state. For example, you - want to include a warning if the method is to be deprecated in - the next release. + warnings that need to be explicitly stated. For example, you + want to include a warning for a method that is to be deprecated + in the next release. Parameters ---------- From 243718711cdd4ee1a1218418d92f08e1d0c909ec Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:34:23 -0400 Subject: [PATCH 17/56] Update ci_cd.rst --- doc/source/library_description/ci_cd.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/library_description/ci_cd.rst b/doc/source/library_description/ci_cd.rst index 86aeb0a34..b17b270a5 100644 --- a/doc/source/library_description/ci_cd.rst +++ b/doc/source/library_description/ci_cd.rst @@ -1,7 +1,7 @@ CI/CD Methods ############# CI/CD (continuous integration/continuous delivery) is -achieved using either public `Azure Devops +achieved using either public `Azure DevOps `_ or public `GitHub Workflow Actions `_ for unit testing, release builds, and documentation builds. From 3d529808e260e2daeef2e4ea9927b74879fa75b0 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:35:50 -0400 Subject: [PATCH 18/56] Update ci_cd.rst --- doc/source/library_description/ci_cd.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/source/library_description/ci_cd.rst b/doc/source/library_description/ci_cd.rst index b17b270a5..2f6db3447 100644 --- a/doc/source/library_description/ci_cd.rst +++ b/doc/source/library_description/ci_cd.rst @@ -10,13 +10,13 @@ For more information, see `Repository Management`. Here are some good examples: -- The `PyAnsys Sphinx documentation theme action `_ - generates Ansys Python package documentation using the `PyAnsys Sphinx theme `__. -- The `MAPDL documentation action `_ - generates MAPDL documentation using product containers. -- The `PyAEDT unit testing action `_ - runs unit testing using an application preinstalled on a self-hosted agent. -- The `MAPDL Azure DevOps action `_ - uses a containerized application to run unit testing for an Azure pipeline. -- The `DPF-Core Azure DevOps action `_ - uses a universal package to run unit testing. +- `PyAnsys Sphinx documentation theme action `_: + Generates Ansys Python package documentation using the `PyAnsys Sphinx theme `__. +- `MAPDL documentation action `_: + Generates MAPDL documentation using product containers. +- `PyAEDT unit testing action `_: + Runs unit testing using an application preinstalled on a self-hosted agent. +- `MAPDL Azure DevOps action `_: + Uses a containerized application to run unit testing for an Azure pipeline. +- `DPF-Core Azure DevOps action `_: + Uses a universal package to run unit testing. From 88268ff9361b3c3212aeb094ea73f1db303122be Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:37:20 -0400 Subject: [PATCH 19/56] Update doc_directory.rst --- doc/source/library_description/doc_directory.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/library_description/doc_directory.rst b/doc/source/library_description/doc_directory.rst index d65745209..10ccad9c4 100644 --- a/doc/source/library_description/doc_directory.rst +++ b/doc/source/library_description/doc_directory.rst @@ -13,4 +13,4 @@ package, including: use case scenarios, and descriptive examples explaining methodologies. - Examples consisting of `Jupyter Notebooks `_. - Contributing section, which can be linked to the general "Contributing" - section in this documentation for the "About" repository. + section in this developer's guide. From 53a01cfe133b93dbb5eb5e1a50e07f6e021a6572 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:39:14 -0400 Subject: [PATCH 20/56] Update index.rst --- doc/source/library_description/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/library_description/index.rst b/doc/source/library_description/index.rst index 8d3429058..9bb1d2cf6 100644 --- a/doc/source/library_description/index.rst +++ b/doc/source/library_description/index.rst @@ -30,7 +30,7 @@ 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 +that maps the raw API into a carefully designed, object-oriented data model and API. From b8501a6e14be022205523b5efaa0346882ed1526 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:41:33 -0400 Subject: [PATCH 21/56] Update index.rst --- doc/source/library_description/index.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/doc/source/library_description/index.rst b/doc/source/library_description/index.rst index 9bb1d2cf6..2c2f6b27d 100644 --- a/doc/source/library_description/index.rst +++ b/doc/source/library_description/index.rst @@ -36,20 +36,21 @@ model and API. Template -------- -Within the `PyAnsys Organization `_ there +Within the `PyAnsys Organization `_, there is a `template repository `_ -where you can `Create a repository from a template`_ and create a new -PyAnsys project that follows the guidelines specified in this guide. +where you can `create a repository from a template`_ and create a +PyAnsys project that follows the guidelines specified in this developer's +guide. -The template repository contains a generalized library skeleton which includes: +The template repository contains a generalized library skeleton that includes: -- Library skeleton with sample classes and methods. -- Sample documentation build including customized templates. -- Sample GitHub Actions specific to PyAnsys projects. -- Licencing, example readme, and setup file -- ``.gitignore`` and other requirements files. +- Library skeleton with sample classes and methods +- Sample documentation build including customized templates +- Sample GitHub actions specific to PyAnsys libraries +- Licensing, example readme, and setup files +- ``.gitignore`` and other requirements files -To use this template, follow the `Create a repository from a +To use this template, follow the `create a repository from a template`_ directions. From ce8262a4966a928a54f562420d37235e67a028fb Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:42:52 -0400 Subject: [PATCH 22/56] Update index.rst --- doc/source/library_description/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/library_description/index.rst b/doc/source/library_description/index.rst index 2c2f6b27d..2b527c6a2 100644 --- a/doc/source/library_description/index.rst +++ b/doc/source/library_description/index.rst @@ -50,8 +50,8 @@ The template repository contains a generalized library skeleton that includes: - Licensing, example readme, and setup files - ``.gitignore`` and other requirements files -To use this template, follow the `create a repository from a -template`_ directions. +To use this template, follow the instructions in `Creating a repository from a +template`_. .. toctree:: From a70b34bfc81543c7dcdba21ce1c5ea2fa318fdc6 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:44:03 -0400 Subject: [PATCH 23/56] Update index.rst --- doc/source/library_description/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/library_description/index.rst b/doc/source/library_description/index.rst index 2b527c6a2..59ff7a1d2 100644 --- a/doc/source/library_description/index.rst +++ b/doc/source/library_description/index.rst @@ -50,7 +50,7 @@ The template repository contains a generalized library skeleton that includes: - Licensing, example readme, and setup files - ``.gitignore`` and other requirements files -To use this template, follow the instructions in `Creating a repository from a +To use this template, follow the instructions for `creating a repository from a template`_. From b3adac13d9409908c642327aad89de62c592feea Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:44:56 -0400 Subject: [PATCH 24/56] Update index.rst --- doc/source/library_description/index.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/source/library_description/index.rst b/doc/source/library_description/index.rst index 59ff7a1d2..9bf3e4539 100644 --- a/doc/source/library_description/index.rst +++ b/doc/source/library_description/index.rst @@ -50,8 +50,7 @@ The template repository contains a generalized library skeleton that includes: - Licensing, example readme, and setup files - ``.gitignore`` and other requirements files -To use this template, follow the instructions for `creating a repository from a -template`_. +To use this template, `create a repository from a template`_. .. toctree:: From d6be072762d5fa2b969d5307f3de021e5e9db20b Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:46:16 -0400 Subject: [PATCH 25/56] Update library_names.rst --- doc/source/library_description/library_names.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/library_description/library_names.rst b/doc/source/library_description/library_names.rst index 756a555f9..02e9ab5d2 100644 --- a/doc/source/library_description/library_names.rst +++ b/doc/source/library_description/library_names.rst @@ -1,6 +1,6 @@ Project, Repository, and Library Names ###################################### -Large organizations who provide many Python packages +Large organizations providing Python packages follow a consistent naming pattern. Ansys follows these naming conventions: @@ -23,4 +23,4 @@ Using long Python library names provides two primary advantages: .. _PyMAPDL: https://github.com/pyansys/pymapdl .. _PyAEDT: https://github.com/pyansys/PyAEDT -.. _Namespace Packages: https://packaging.python.org/guides/packaging-namespace-packages/ \ No newline at end of file +.. _Namespace Packages: https://packaging.python.org/guides/packaging-namespace-packages/ From 791cdb10d2caa2bd5afaf9e51ca14b70b8efde7a Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:47:45 -0400 Subject: [PATCH 26/56] Update license.rst --- doc/source/library_description/license.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/library_description/license.rst b/doc/source/library_description/license.rst index 1d02bde46..922a01c63 100644 --- a/doc/source/library_description/license.rst +++ b/doc/source/library_description/license.rst @@ -2,8 +2,8 @@ License File ############ -PyAnsys projects are expected to have this exact license included in -the root directory of their project. +PyAnsys libraries are expected to have this license file included in +the root directory of their repositories. ------------ From 55503297ba0ba2e7364121babe9c4814fa0962a4 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:59:01 -0400 Subject: [PATCH 27/56] Update packaging.rst --- doc/source/library_description/packaging.rst | 56 +++++++++++--------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index b710b57d5..fa63ae48d 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -1,14 +1,15 @@ Packaging ######### -Python packages are used to organize and structure a Python library containing several modules and assets such as examples or binary extensions. -They offer an easy, reliable and comprehensive way to distribute and install -Python libraries on a variety of platforms and environments. +A Python package organizes and structures a Python library containing several +modules and assets such as examples or binary extensions. A Python package +offers an easy, reliable, and comprehensive way to distribute and install +a Python library on a variety of platforms and environments. Namespace Packaging ------------------- -PyAnsys libraries use the `namespace packaging`_. -Namespace packages allow the user to easily split subpackages from a package into -a single and an independent distribution. +A PyAnsys library uses the `namespace packaging`_. +Namespace packages allow a user to easily split subpackages from a package into +a single, independent distribution. Three different approaches are currently available to create a namespace package: @@ -16,24 +17,24 @@ Three different approaches are currently available to create a namespace package * pkgutil-style namespace packages * pkg_resources-style namespace packages -Required files +Required Files -------------- -* README.rst file is used to describe the purpose of the package. +* README.rst file describes the purpose of the package. *The format of this file must be reStructuredText.* -* LICENSE file to specify the copyrigths and required authorization. +* LICENSE file specifies copyrights and required authorization. -* setup.py file to provide package main information. - The presence of this file indicate that the package was likely created using disutils - which is the Python standard for building and distributing python package. +* setup.py file provides package information. + The presence of this file indicate that the package was likely created using disutils, + which is the Python standard for building and distributing a Python package. Setup File ---------- The `setup.py`_ file is the build script for ``setuptools``. It exposes dynamic metadata and contains -package's main information such as description, author, and version. -In this file, the ``setuptools`` module will be used to configure the metadata as opposed to ``distutils``, +package information, such as a description and the author and version. +In this file, the ``setuptools`` module is used to configure the metadata (as opposed to ``distutils``). .. code:: python @@ -51,14 +52,15 @@ package. packages.append(package) -It also extracts the version number from the ``_version.py`` located in the ``ansys//library`` directory of the source code. +It also extracts the version number from the ``_version.py`` file located in the +``ansys//library`` directory of the source code. -Generate the Package and Upload it on PyPI +Generate the Package and Upload It on PyPI ------------------------------------------ -The first time you want to upload a package on PyPI under the `ansys `_ account, you must perform the following -process manually: +The first time that you want to upload a package on PyPI under the `ansys `_ +account, you must perform the following process manually. Create the python package. @@ -73,20 +75,24 @@ Verify the distribution's long description rendering with ``twine``. pip install twine twine check dist/* -Upload the package to PyPI using ``twine`` using the upload token generated for the ``ansys`` PyPI account. Contact alexander.kaszynski@ansys.com for the token. +Upload the package to PyPI using ``twine`` and the upload token generated for the ``ansys`` PyPI account. +Contact alexander.kaszynski@ansys.com for the token. .. code:: python -m twine upload -u __token__ -p --skip-existing dist/* -Then, for the next release upload, you can do it through the CI/CD workflow after generating a token just for this package. +For the next release upload, you can do it through the CI/CD workflow after generating a token just for this package. Create a `secret`_ in GitHub settings. Name it ``PYPI_TOKEN`` and assign it the token provided by PyPI. This token will be reused in the CI/CD workflow handling the package distribution. Tag a Release ------------- -In order to deploy a new package on PyPI, you must tag a release under a release branch. The PyAnsys project follows the `trunk-based development`_ source-control branching model, where the main development branch is always in a releasable state. +To deploy a new package on PyPI, you must tag a release under a release branch. The PyAnsys project +follows the `trunk-based development`_ source-control branching model, where the main development +branch is always in a releasable state. + To tag the release, you must update your main local branch. .. code:: @@ -94,7 +100,7 @@ To tag the release, you must update your main local branch. git checkout main git pull -Then, create the new release branch +Then, create the new release branch. .. code:: @@ -109,17 +115,17 @@ Commit and push your changes and then create the tag: git tag v git push --tags -Finally, following this tag creation, the workflow responsible for the distribution +Following this tag creation, the workflow responsible for the distribution will be automatically triggered. -Install a package +Install a Package ----------------- .. code:: pip install ansys.. -Here is the minimal content of your python project to create a package complying with the above standards. +To create a package complying with the above standards, here is the minimal content of your PyAnsys libary: .. code:: From 318281e1b0e3401eb9101f35257bafc48ac69d74 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:59:32 -0400 Subject: [PATCH 28/56] Update packaging.rst --- doc/source/library_description/packaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index fa63ae48d..d4fa00c54 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -1,6 +1,6 @@ Packaging ######### -A Python package organizes and structures a Python library containing several +A Python package organizes and structures a Python library, which contains several modules and assets such as examples or binary extensions. A Python package offers an easy, reliable, and comprehensive way to distribute and install a Python library on a variety of platforms and environments. From ced80959cd9da6584313febca1023b1c53c41d7b Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:59:59 -0400 Subject: [PATCH 29/56] Update packaging.rst --- doc/source/library_description/packaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index d4fa00c54..aca8dd5d9 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -7,7 +7,7 @@ a Python library on a variety of platforms and environments. Namespace Packaging ------------------- -A PyAnsys library uses the `namespace packaging`_. +A PyAnsys library uses `namespace packaging`_. Namespace packages allow a user to easily split subpackages from a package into a single, independent distribution. From 1abf9dce130abe08000540b144f42616122996f6 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:00:43 -0400 Subject: [PATCH 30/56] Update packaging.rst --- doc/source/library_description/packaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index aca8dd5d9..6e3dbab2a 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -11,7 +11,7 @@ A PyAnsys library uses `namespace packaging`_. Namespace packages allow a user to easily split subpackages from a package into a single, independent distribution. -Three different approaches are currently available to create a namespace package: +Three different approaches are currently available for creating a namespace package: * `native namespace packages`_ * pkgutil-style namespace packages From a90f311a09aab2d1944099e5f09b9b682bd11715 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:01:41 -0400 Subject: [PATCH 31/56] Update packaging.rst --- doc/source/library_description/packaging.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index 6e3dbab2a..fe1af2f1c 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -20,12 +20,12 @@ Three different approaches are currently available for creating a namespace pack Required Files -------------- -* README.rst file describes the purpose of the package. +* README.rst file, which describes the purpose of the package. *The format of this file must be reStructuredText.* -* LICENSE file specifies copyrights and required authorization. +* LICENSE file, which specifies copyrights and required authorization. -* setup.py file provides package information. +* setup.py file, which provides package information. The presence of this file indicate that the package was likely created using disutils, which is the Python standard for building and distributing a Python package. From 89dd739a83cdb7a3fb15f60003291672c9769bb2 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:02:31 -0400 Subject: [PATCH 32/56] Update packaging.rst --- doc/source/library_description/packaging.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index fe1af2f1c..933f960d1 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -20,12 +20,12 @@ Three different approaches are currently available for creating a namespace pack Required Files -------------- -* README.rst file, which describes the purpose of the package. +* README.rst file: Describes the purpose of the package. *The format of this file must be reStructuredText.* -* LICENSE file, which specifies copyrights and required authorization. +* LICENSE file: Specifies copyrights and required authorization. -* setup.py file, which provides package information. +* setup.py file: Provides package information. The presence of this file indicate that the package was likely created using disutils, which is the Python standard for building and distributing a Python package. From 7036aabab677140ff040c369b6d6626534cda107 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:03:47 -0400 Subject: [PATCH 33/56] Update packaging.rst --- doc/source/library_description/packaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index 933f960d1..28e794968 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -33,7 +33,7 @@ Required Files Setup File ---------- The `setup.py`_ file is the build script for ``setuptools``. It exposes dynamic metadata and contains -package information, such as a description and the author and version. +package information, such as a description, author, and version. In this file, the ``setuptools`` module is used to configure the metadata (as opposed to ``distutils``). .. code:: python From 73f129fe565a5c68ac54e1b7dda13681586c9bbd Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:04:20 -0400 Subject: [PATCH 34/56] Update packaging.rst --- doc/source/library_description/packaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index 28e794968..d743aa105 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -26,7 +26,7 @@ Required Files * LICENSE file: Specifies copyrights and required authorization. * setup.py file: Provides package information. - The presence of this file indicate that the package was likely created using disutils, + The presence of this file indicate that the package was likely created using ``disutils``, which is the Python standard for building and distributing a Python package. From b369b01f8c043d91c27b037db0f08161475ac460 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:06:44 -0400 Subject: [PATCH 35/56] Update packaging.rst --- doc/source/library_description/packaging.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index d743aa105..c6e73aedc 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -93,21 +93,21 @@ To deploy a new package on PyPI, you must tag a release under a release branch. follows the `trunk-based development`_ source-control branching model, where the main development branch is always in a releasable state. -To tag the release, you must update your main local branch. +To tag the release, update your main local branch. .. code:: git checkout main git pull -Then, create the new release branch. +Then, create a release branch. .. code:: git checkout -b release/MAJOR.MINOR Bump the version number in the ``_version`` file to ``MAJOR.MINOR.PATCH``. -Commit and push your changes and then create the tag: +Commit and push your changes and then create the tag. .. code:: From c8f2a0a26b13c191c5f6f183c02c4e87a7629024 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:07:21 -0400 Subject: [PATCH 36/56] Update packaging.rst --- doc/source/library_description/packaging.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index c6e73aedc..0d531aa85 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -107,6 +107,7 @@ Then, create a release branch. git checkout -b release/MAJOR.MINOR Bump the version number in the ``_version`` file to ``MAJOR.MINOR.PATCH``. + Commit and push your changes and then create the tag. .. code:: From e7397932190fcf2344e01c7dc891769e77e68691 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:09:08 -0400 Subject: [PATCH 37/56] Update packaging.rst --- doc/source/library_description/packaging.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index 0d531aa85..81a7beb9a 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -121,6 +121,7 @@ will be automatically triggered. Install a Package ----------------- +Install a package with: .. code:: From d1bf06aa87e46c23d98d3e88f35016d11ae71edb Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:09:59 -0400 Subject: [PATCH 38/56] Update readme_file.rst --- doc/source/library_description/readme_file.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/library_description/readme_file.rst b/doc/source/library_description/readme_file.rst index cb19d7756..e07ac735c 100644 --- a/doc/source/library_description/readme_file.rst +++ b/doc/source/library_description/readme_file.rst @@ -1,6 +1,6 @@ README File ########### -Each PyAnsys project should have a README file in the root directory. +Each PyAnsys library should have a README file in the root directory. To create this file, use either `reStructuredText Markup Syntax`_ to create a file named ``README.rst`` or `Markdown Syntax`_ to create a file named ``README.md`` From 4271916591586888a70a69c8b0e793006d4dd2fb Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:10:51 -0400 Subject: [PATCH 39/56] Update repo_directory_structure.rst --- doc/source/library_description/repo_directory_structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/library_description/repo_directory_structure.rst b/doc/source/library_description/repo_directory_structure.rst index dc333cc61..1da6fcb45 100644 --- a/doc/source/library_description/repo_directory_structure.rst +++ b/doc/source/library_description/repo_directory_structure.rst @@ -3,7 +3,7 @@ Repository Directory Structure The source for a PyAnsys library is hosted in an individual repository under the `PyAnsys Organization Account `__. The repository should contain -the source, documentation, and unit testing of the project in +the source, documentation, and unit testing of the library in this directory structure: :: From 426514e9c0a69b2a2ee5f9f199fdca1e677c5415 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:14:49 -0400 Subject: [PATCH 40/56] Update source_organization.rst --- doc/source/library_description/source_organization.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/doc/source/library_description/source_organization.rst b/doc/source/library_description/source_organization.rst index 7611bc890..a14289e7c 100644 --- a/doc/source/library_description/source_organization.rst +++ b/doc/source/library_description/source_organization.rst @@ -26,15 +26,13 @@ This allows the `PyMAPDL`_ library to be imported with: >>> from ansys.mapdl import core as pymapdl When using this convention, other namespace packages can use the -``ansys-mapdl`` namespace. - -For example: +``ansys-mapdl`` namespace. .. code:: python >>> from ansys.mapdl import reader as pymapdl_reader -.. note:: +**Note** Do not include ``__init__.py`` in first-level and second-level directories. If ``__init__.py`` is included in these levels, @@ -46,4 +44,4 @@ to share the same namespace. This makes it easy when searching for "ansys" packages within the `Python Package Index PyPi `_. .. _Namespace Packages: https://packaging.python.org/guides/packaging-namespace-packages/ -.. _PyMAPDL: https://github.com/pyansys/pymapdl \ No newline at end of file +.. _PyMAPDL: https://github.com/pyansys/pymapdl From 2864d9ec5f873e4108eaa4194254fcab1f8a696c Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:35:20 -0400 Subject: [PATCH 41/56] Update administration.rst --- doc/source/overview/administration.rst | 68 +++++++++++++------------- 1 file changed, 33 insertions(+), 35 deletions(-) diff --git a/doc/source/overview/administration.rst b/doc/source/overview/administration.rst index a3beb8600..0db650dd9 100644 --- a/doc/source/overview/administration.rst +++ b/doc/source/overview/administration.rst @@ -12,17 +12,16 @@ Licensing and Approval 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``. +restrictions. This follows the pattern of including PyAnsys as a +dependency in ``install_requires`` in the ``setup.py`` file. 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 make your library suitable for commercial use, you need only 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. +directory of the repository of every PyAnsys library. Project Approval @@ -35,41 +34,40 @@ Stephane Marguerin or Alexander Kaszynski for any requests. Repository Management and Standards =================================== Each PyAnsys repository should at the minimum be administrated by a -single individual with "Admin" permissions over the repository. This +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). +settings for that repository, such as GitHub pages, repository +description, or branch protection management. -Each repository is expected to follow a minimum set of standards: +Each repository is expected to follow this minimum set of standards: -- Minimum code standards following PEP8 and described in -- CI/CD using GitHub actions or Azure Devops enforcing coding standards. -- Publicly hosted documentation detailing API with examples. See +- Minimum code standards following PEP8. See :ref:`best_practices`. +- CI/CD using GitHub actions or Azure DevOps to enforce coding standards. See :ref:`ci_cd`. +- Publicly hosted documentation detailing API with examples. See :ref:`api_documentation`. -- Unit testing with at least 80% test coverage. +- Unit testing with at least 80% test coverage. See :ref:`ci_cd`. - Infrastructure in place to deploy the library as a package on `PyPi - `_ -- Proper license file and author (see :ref:`setup_file` and `ref:`license_file`) + `_. See :ref:`packaging`. +- Proper license file and author. See :ref:`setup_file` and `ref:`license_file`. Release Procedures and Versioning ================================= -PyAnsys library project releases are managed through both automated +PyAnsys library releases are managed through both automated and manual review processes. PyAnsys follows the `Semantic Versioning`_ process as closely as possible: -* **Major** version when you make incompatible API changes, -* **Minor** version when you add functionality in a backwards compatible manner, and +* **Major** version when you make incompatible API changes. +* **Minor** version when you add functionality in a backwards compatible manner. * **Patch** version when you make backwards compatible bug fixes. -With one exception: MAJOR versions are not expected to be regularly -released with any incompatible API changes. They are only expected to -released with major globally breaking API changes. This matches the -versioning for the "big three", `NumPy`_, `SciPy`_, and `pandas`_. +One exception exists. MAJOR versions are not expected to be regularly +released with any incompatible API changes. They are only expected to +be released with major, globally-breaking API changes. This matches the +versioning for the "big three": `NumPy`_, `SciPy`_, and `pandas`_. .. _Semantic Versioning: https://semver.org/ .. _NumPy: https://numpy.org/ @@ -82,24 +80,24 @@ Release Definition **Major** -Major releases denote global major, breaking API changes. Adding or -changing a feature is not considered a globally backwards incompatible -API change. Rather, a major release and version bump should be made -these are globally breaking changes are made that will require a +Major releases denote global, major breaking API changes. Adding or +changing a feature is not considered a globally-backwards incompatible +API change. Rather, a major release and version bump should be made +if globally-breaking changes are made that will require a signifiant refactor of any dependent modules. -Another note is ``0.MINOR.PATCH`` packges are expected to have fluid -APIs, and should be solidified at the ``1.MINOR.PATCH`` release. At +Note that ``0.MINOR.PATCH`` packges are expected to have fluid +APIs and should be solidified at the ``1.MINOR.PATCH`` release. At that point, APIs are expected to be much more stable. **Minor** Minor releases are feature releases that improve the functionality and -stability of PyAnsys libraries. +stability of a PyAnsys library. **Patch** -Patch releases are for critical and important bugfixes that can not or +Patch releases are for critical and important bug fixes that cannot or should not wait until a minor release. @@ -113,8 +111,8 @@ See :ref:`release_procedures` for the details on release management. Product Version Matching ------------------------ -PyAnsys libraries should not match product versions. For example, the -PyMAPDL library ``ansys-mapdl-core`` may have the version ``0.59.0`` -whereas the product will be versioned 21.2 (i.e. 2021R2). The reason +PyAnsys libraries should not match product versions. For example, the +PyMAPDL library ``ansys-mapdl-core`` might have the version ``0.59.0`` +whereas the product version is 21.2 (2021 R2). The reason behind this is PyAnsys libraries are expected to be developed outside the product release cycle in a rapid CI/CD manner. From 3c56c94006d40dbd936c8934fdf7c215799fc9cc Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:47:15 -0400 Subject: [PATCH 42/56] Update contributing.rst --- doc/source/overview/contributing.rst | 73 ++++++++++++++-------------- 1 file changed, 37 insertions(+), 36 deletions(-) diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst index a24127eb7..23d943cfa 100644 --- a/doc/source/overview/contributing.rst +++ b/doc/source/overview/contributing.rst @@ -1,18 +1,17 @@ -============================== -Contributing - Getting Started -============================== +============ +Contributing +============ -This is intended to be a quick start guide for those who want to start +This page provides a quick start guide for anyone who wants to start contributing to a PyAnsys library. -We welcome all code contributions and hope that this guide facilitate -an understanding of the PyAnsys code repository. It is important to -note that while PyAnsys libaries is maintained by Ansys and all -submissions are reviewed thoroughly before merging, our goal is to -foster a community that can support user questions and develop new -features to make PyAnsys libaries a powerful tool for all users. As -such, we welcome and encourage the submittal of questions and code to -this repository. +We welcome all code contributions and hope that this developer's guide +facilitates an understanding of the PyAnsys code repository. It is important to +note that while Ansys maintains all PyAnsys libaries and thoroughly reviews all +submissions before merging, our goal is to foster a community that can support +user questions and develop new features to make PyAnsys libaries powerful tools +for all users. As such, we welcome and encourage the submittal of questions and +code to this repository and all PyAnsys library repositories. Contributing New Code @@ -28,32 +27,34 @@ develop your code and adhere to PyAnsys repository standards. Feature Requests ---------------- -We encourage users to submit ideas for improvements to PyAEDT. To -suggest an improvement, create an issue on the respective Issues page with -a ``Feature Request`` label. Use a descriptive title and provide ample -background information to help the community implement the desired -functionality. For example, if you would like a reader for a specific -file format, provide a link to documentation of this file format and -possibly provide some sample files and screenshots. We will use the -issue thread as a place to discuss and provide feedback. +We encourage users to submit ideas for improvements to PyAnsys libraries. +To suggest an improvement, create an issue on the Issues page for the +respective PyAnsys library and tag it with a ``Feature Request`` label. + +Use a descriptive title and provide ample background information to help +the community implement the desired functionality. For example, if you +would like a reader for a specific file format, provide a link to +documentation of this file format and possibly provide some sample files +and screenshots. We will use the issue thread as a place to discuss and +provide feedback. Reporting Bugs -------------- -If you encounter a bugs or your workflow crashes while using a PyAnsys -library, please create an issue on the respective `issues`_ page with an -appropriate label so that it can be promptly addressed. When reporting -an issue, be as descriptive as possible so that the issue can be -reproduced. Whenever possible, provide a traceback, screenshot, and -sample files to help us address the issue. +If you encounter a bug or your workflow crashes while using a PyAnsys +library, please create an issue on the `issues`_ page for the respective +PyAnsys library and tag it with an appropriate label so that it can be +promptly addressed. When reporting an issue, be as descriptive as possible +so that the issue can be reproduced. Whenever possible, provide a traceback, +screenshot, and sample files to help us address the issue. .. _issues: Issues ------ -For general or technical questions about pyAEDT, its applications, or -about software usage, you can create issues for the applicable respsitory at: +For general or technical questions about a PyAnsys libary, its applications, or +about software usage, you can create issues for the applicable repository at: - `PyAEDT Issues `_ - `PyMAPDL Issues `_ @@ -61,18 +62,18 @@ about software usage, you can create issues for the applicable respsitory at: This way, the community or PyAnsys developers can collectively address them. The project support team can be reached at -pyansys.support@ansys.com, and someone will respond or direct the +pyansys.support@ansys.com. Someone will respond or direct the message accordingly. Discussions ~~~~~~~~~~~ -General questions regarding development practices should be raised in -the correspoinding repository (for example `Discussions -`_) rather than as -issues themselves. Issues can be spun out of discussions depending on -what is decided, but general Q&A content should start as discussions -where possible. +General questions regarding development practices should be raised as +discussions in the repository for the corresponding PyAnsys library +rather than as issues. For example, general questions about PyMAPDL should be raised +in the PyMAPDL `Discussions `_. +Issues can be spun out of discussions depending on what is decided, but general +questions should start as discussions where possible. Installing from Source @@ -94,7 +95,7 @@ For example: cd pymapdl pip install -e . -Consider creating a fork of the repository if you wish to eventually +Consider creating a fork of the repository if you want to eventually push a contribution to the offical PyAnsys repository. .. https://docs.github.com/en/get-started/quickstart/fork-a-repo From e2c47c71ad32b54a02fc646fbf515de7acb01cb1 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:48:37 -0400 Subject: [PATCH 43/56] Update contributing.rst --- doc/source/overview/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst index 23d943cfa..95f910459 100644 --- a/doc/source/overview/contributing.rst +++ b/doc/source/overview/contributing.rst @@ -71,7 +71,7 @@ Discussions General questions regarding development practices should be raised as discussions in the repository for the corresponding PyAnsys library rather than as issues. For example, general questions about PyMAPDL should be raised -in the PyMAPDL `Discussions `_. +in the `PyMAPDL Discussions `_. Issues can be spun out of discussions depending on what is decided, but general questions should start as discussions where possible. From aee63ceafd7478d43c3b0927d753e7eae264d4f6 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:50:08 -0400 Subject: [PATCH 44/56] Update contributing.rst --- doc/source/overview/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst index 95f910459..a27efce0a 100644 --- a/doc/source/overview/contributing.rst +++ b/doc/source/overview/contributing.rst @@ -21,7 +21,7 @@ creating an issue as a feature request. We will then use this thread to discuss how best to implement the contribution. Once you are ready to start coding, see the -:ref:`development_practices` section for more information on how to +:ref:`best_practices` section for more information on how to develop your code and adhere to PyAnsys repository standards. From 498a397b421e607675d5d524154e7faf58e33422 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:51:59 -0400 Subject: [PATCH 45/56] Update contributing.rst --- doc/source/overview/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst index a27efce0a..c73cb841b 100644 --- a/doc/source/overview/contributing.rst +++ b/doc/source/overview/contributing.rst @@ -110,4 +110,4 @@ responsibility to ensure that the existing license is compatible and included in the contributed files. You must obtain permission from the original author to relicense the code. -See :ref:`license_file` for more details. +See :ref:`license` for more details. From d7c8bca70ff71d73d36fba6536f3cf41c203ecb2 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 18:53:30 -0400 Subject: [PATCH 46/56] Update administration.rst --- doc/source/overview/administration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/overview/administration.rst b/doc/source/overview/administration.rst index 0db650dd9..df30186b5 100644 --- a/doc/source/overview/administration.rst +++ b/doc/source/overview/administration.rst @@ -48,7 +48,7 @@ Each repository is expected to follow this minimum set of standards: - Unit testing with at least 80% test coverage. See :ref:`ci_cd`. - Infrastructure in place to deploy the library as a package on `PyPi `_. See :ref:`packaging`. -- Proper license file and author. See :ref:`setup_file` and `ref:`license_file`. +- Proper license file and author. See :ref:`setup_file` and :ref:`license_file`. Release Procedures and Versioning From 1690ae88058f13963883f828056b31527b87f68c Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 19:17:45 -0400 Subject: [PATCH 47/56] Update dev_practices.rst --- doc/source/overview/dev_practices.rst | 140 +++++++++++++------------- 1 file changed, 69 insertions(+), 71 deletions(-) diff --git a/doc/source/overview/dev_practices.rst b/doc/source/overview/dev_practices.rst index ec034547d..d194fa238 100644 --- a/doc/source/overview/dev_practices.rst +++ b/doc/source/overview/dev_practices.rst @@ -3,7 +3,7 @@ Development Practices ===================== -This section provides a guide to how we conduct development in PyAnsys +This section explains how development is conducted in PyAnsys repositories. Please follow the practices outlined here when contributing directly to PyAnsys. @@ -11,8 +11,9 @@ contributing directly to PyAnsys. General Development Procedures ------------------------------ -To submit new code to a PyAnsys, first `fork `_ the repository (for example `PyMAPDL `_) and then clone the forked -repository to your computer. Next, create a new branch based on the +To submit new code to a PyAnsys, first `fork `_ +the repository (for example `PyMAPDL `_) +and then clone the forked repository to your computer. Next, create a new branch based on the `Branch Naming Conventions Section <#branch-naming-conventions>`__ in your local repository. @@ -22,15 +23,14 @@ your change is complex. Also, be sure to test often. See the `Testing Section <#testing>`__ below for automating testing. When you are ready to submit your code, create a pull request by -following the steps in the `Creating a New Pull Request -section <#creating-a-new-pull-request>`__. +following the steps in `Creating a New Pull Request <#creating-a-new-pull-request>`__. -Be sure to reference our: +Be sure to review these topics: #. `Branching Section <#Branching Model>`__ #. Testing standards. -#. Documentation standards. See :ref:`api_documentation`. -#. Code quality standards. See :ref:`coding_style`. +#. Documentation standards. See :ref:`api_documentation`. +#. Code quality standards. See :ref:`coding_style`. Guidelines @@ -38,26 +38,26 @@ Guidelines Consider the following general coding paradigms when contributing: -1. Follow the `Zen of Python `__. As - silly as the core Python developers are sometimes, there's much to +1. Follow the `Zen of Python `__. + As silly as the core Python developers are sometimes, there's much to be gained by following the basic guidelines listed in PEP 20. Without repeating them here, focus on making your additions - intuitive, novel, and helpful for PyMAPDL and its users. + intuitive, novel, and helpful for users. - When in doubt, ``import this`` + When in doubt, ``import this``. 2. **Document it**. Include a docstring for any function, method, or - class added. Follow the `numpydocs docstring + class added. Follow the `numpydocs docstring `_ guidelines, and always provide an example of simple use cases for - the new features. + new features. -3. **Test it**. Since Python is an interperted language, if it's not - tested, it's probably broken. At the minimum, include unit tests - for each new feature within the ``tests`` directory. Ensure that +3. **Test it**. Because Python is an interperted language, if it's not + tested, it's probably broken. At the minimum, include unit tests + for each new feature within the ``tests`` directory. Ensure that each new method, class, or function has reasonable (>80%) coverage. -Additionally, please do not include any data sets for which a license +Additionally, do not include any data sets for which a license is not available or commercial use is prohibited. Licensing @@ -75,35 +75,34 @@ See :ref:`license_file` for more details. Branching Model --------------- This project has a branching model that enables rapid development of -features without sacrificing stability, and closely follows the +features without sacrificing stability and closely follows the `Trunk Based Development `_ approach. -The main features of our branching model are: +Descriptions follow for the main features of the branching model. -- The `main` branch is the main development branch. All features, - patches, and other branches should be merged here. While all PRs - should pass all applicable CI checks, this branch may be - functionally unstable as changes might have introduced unintended - side-effects or bugs that were not caught through unit testing. +- The `main` branch is the main development branch. All features, + patches, and other branches should be merged here. While all pull + requests (PRs) should pass all applicable CI (Continuous Integration) + checks, this branch might be functionally unstable if changes have + introduced unintended side-effects or bugs that were not caught through + unit testing. - There will be one or many `release/` branches based on minor - releases (for example `release/0.2`) which contain a stable version - of the code base that is also reflected on PyPi/. Hotfixes from + releases (for example, `release/0.2`) that contain a stable version + of the code base that is also reflected on PyPi. Hotfixes from `fix/` branches should be merged both to main and to these - branches. When necessary to create a new patch release these + branches. When creating a new patch release is necessary, these release branches will have their `__version__.py` updated and be - tagged with a patched semantic version (e.g. `0.2.1`). This - triggers CI to push to PyPi, and allow us to rapidly push hotfixes - for past versions of ``ansys.mapdl.core`` without having to worry about - untested features. + tagged with a patched semantic version (for example, `0.2.1`). This + triggers CI to push to PyPi and allow us to rapidly push hotfixes + for past versions without having to worry about untested features. - When a minor release candidate is ready, a new `release` branch will be created from `main` with the next incremented minor version - (e.g. `release/0.2`), which will be thoroughly tested. When deemed - stable, the release branch will be tagged with the version (`0.2.0` - in this case), and if necessary merged with main if any changes - were pushed to it. Feature development then continues on `main` - and any hotfixes will now be merged with this release. Older - release branches should not be deleted so they can be patched as - needed. + (for example, `release/0.2`), This `release` branch will be thoroughly + tested. When deemed stable, it will be tagged with the version (`0.2.0` + in this case) and merged with `main` if any changes were pushed to it. + Feature development then continues on `main` and any hotfixes will now + be merged with this release. Older release branches should not be deleted + so they can be patched as needed. .. _release_procedures: @@ -112,17 +111,17 @@ Release Procedures Major and Minor ~~~~~~~~~~~~~~~ -These are the procetures for major and minor releases. +Procedures follow for major and minor releases. -#. Create a new branch from the ``main`` branch with name - ``release/MAJOR.MINOR`` (e.g. `release/0.2`). +#. Create a new branch from the `main` branch with name + `release/MAJOR.MINOR`(for example, `release/0.2`). #. Locally run all tests as outlined in :ref:`testing` and ensure all are passing. #. Locally test and build the documentation with link checking to make -sure no links are outdated. Be sure to run `make clean` to ensure no -results are cached. + sure no links are outdated. Be sure to run ``make clean`` to ensure no + results are cached. .. code:: @@ -131,23 +130,23 @@ results are cached. make html -b linkcheck #. After building the documentation, open the local build and examine - the examples gallery for any obvious issues. + the examples for any obvious issues. #. Update the version numbers in ``ansys///_version.py`` and commit it. Push the branch to GitHub and create a new PR for this release that merges - it to main. Development to main should be limited at this point - while effort is focused on the release. - -#. It is now the responsibility of the PyMAPDL community and - developers to functionally test the new release. It is best to - locally install this branch and use it in production. Any bugs - identified should have their hotfixes pushed to this release - branch. - -#. When the branch is deemed as stable for public release, the PR will - be merged to main and the `main` branch will be tagged with a - `MAJOR.MINOR.0` release. The release branch will not be deleted. + it to `main`. Development to `main` should be limited while + effort is focused on the release. + +#. The community and Ansys developers must now functionally test the + new release. It is best to locally install this branch and use it in + production. Any bugsidentified should have their hotfixes pushed to + this release branch. + +#. When the branch is deemed as stable for public release, the PR ismerged + to `main` branch, which is then tagged with a `MAJOR.MINOR.0` release. + The release branch will not be deleted. + Tag the release with: .. code:: @@ -156,13 +155,13 @@ results are cached. git push origin --tags #. Create a list of all changes for the release. It is often helpful - to leverage to see the `GitHub's compare feature`_ differences from + to see the `GitHub's compare feature`_ differences from the last tag and the `main` branch. Be sure to acknowledge new contributors by their GitHub username and place mentions where - appropriate if a specific contributor is to thank for a new + appropriate if a specific contributor is to be thanked for a new feature. -#. Place your release notes from step 8 in the release section with GitHub. See +#. Place your release notes from step 8 in the release section with GitHub. See `GitHub Releases`_ .. _GitHub Releases: https://docs.github.com/en/github/administering-a-repository/releasing-projects-on-github/managing-releases-in-a-repository @@ -171,22 +170,21 @@ results are cached. Patch Release Steps ~~~~~~~~~~~~~~~~~~~ -Patch releases are for critical and important bugfixes that can not or -should not wait until a minor release. The steps for a patch release +Patch releases are for critical and important bug fixes that cannot or +should not wait until a minor release. These are the steps for a patch release: -1. Push the necessary bugfix(es) to the applicable release branch. - This will generally be the latest release branch - (e.g. ``release/MAJOR.MINOR``). +1. Push the necessary bug fixes to the applicable release branch. + This will generally be the latest release branch (`release/MAJOR.MINOR`). 2. Update ``__version__.py`` with the next patch increment - (e.g. ``MAJOR.MINOR.PATCH``), commit it, and open a PR that merge with the - release branch. This gives the PyMAPDL developers and community - a chance to validate and approve the bugfix release. Any + (`MAJOR.MINOR.PATCH`), commit it, and open a PR to merge with the + release branch. This gives the developers and community + an opportunity to validate and approve the bug fix release. Any additional hotfixes should be outside of this PR. -3. When approved, merge with the release branch, but not ``main`` as - there is no reason to increment the version of the ``main`` branch. - Then create a tag from the release branch with the applicable +3. When approved, merge with the release branch, but not `main` as + there is no reason to increment the version of the `main` branch. + Then, create a tag from the release branch with the applicable version number (see above for the correct steps). 4. If deemed necessary, add a release notes page. From afc27a694d290de132874342bc9aa1ded7b41960 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 19:18:25 -0400 Subject: [PATCH 48/56] Update dev_practices.rst --- doc/source/overview/dev_practices.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/overview/dev_practices.rst b/doc/source/overview/dev_practices.rst index d194fa238..fff71474b 100644 --- a/doc/source/overview/dev_practices.rst +++ b/doc/source/overview/dev_practices.rst @@ -5,7 +5,7 @@ Development Practices This section explains how development is conducted in PyAnsys repositories. Please follow the practices outlined here when -contributing directly to PyAnsys. +contributing directly to PyAnsys libraries. General Development Procedures From 9d7aefb3587772a317fb01770b61d77c36aecab0 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 19:20:53 -0400 Subject: [PATCH 49/56] Update index.rst --- doc/source/overview/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst index 766e69340..2e0022667 100644 --- a/doc/source/overview/index.rst +++ b/doc/source/overview/index.rst @@ -6,20 +6,20 @@ expose Ansys technologies to the Python ecosystem. These libraries are more than reusable scripts. They are clear, concise, and maintainable APIs and interfaces. Their useful functions, classes, and plugins eliminate the need to write scripts interfacing with low -level APIs, but rather interact with the product or service at a high -level, object orientated manner. +level APIs, allowing you to now interact with the product or service +at a high level in an object-orientated manner. These libraries play a vital role in: - Application automation - Machine learning -- Post-processing +- Postprocessing - Data visualization - Workflow orchestration - Data manipulation and export The libraries also include plugins and interfaces to the vast python -ecosystem. For example: +ecosystem. Examples include: - Arrays using `NumPy `_ - Data structures and tables with `pandas `_ From 4a7d5686c9f3efceb015c4cdc5a592eb6dcf87c3 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 19:21:30 -0400 Subject: [PATCH 50/56] Update index.rst --- doc/source/overview/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst index 2e0022667..5620c8d33 100644 --- a/doc/source/overview/index.rst +++ b/doc/source/overview/index.rst @@ -24,7 +24,7 @@ ecosystem. Examples include: - Arrays using `NumPy `_ - Data structures and tables with `pandas `_ - 2D visualization using `Matplotlib `_ -- 3D visualization using `pyvista `_ +- 3D visualization using `PyVista `_ - Advanced scientific computing using `scipy `_ - Machine learning using `TensorFlow `_ From 219f399dd3a485e8313331d24a25e7be6d04a12e Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 19:22:00 -0400 Subject: [PATCH 51/56] Update index.rst --- doc/source/overview/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst index 5620c8d33..7a01206e8 100644 --- a/doc/source/overview/index.rst +++ b/doc/source/overview/index.rst @@ -25,7 +25,7 @@ ecosystem. Examples include: - Data structures and tables with `pandas `_ - 2D visualization using `Matplotlib `_ - 3D visualization using `PyVista `_ -- Advanced scientific computing using `scipy `_ +- Advanced scientific computing using `SciPy `_ - Machine learning using `TensorFlow `_ From fce9c1aa0498f897c566f44af4bef6f36e9f32be Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 19:22:56 -0400 Subject: [PATCH 52/56] Update index.rst --- doc/source/overview/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst index 7a01206e8..b2fc88d0a 100644 --- a/doc/source/overview/index.rst +++ b/doc/source/overview/index.rst @@ -37,7 +37,7 @@ The PyAnsys project is hosted on GitHub at `PyAnsys Python libraries that interface with Ansys products or services. To try out a library, visit one of these links: -* `PyAnsys Packages Overview `_ +* `PyAnsys Project `_ * `PyMAPDL`_ * `PyAEDT`_ * `DPF-Core `_ From ac332f4edd157b69bc825e7bbe2e34238e6978ef Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 19:23:46 -0400 Subject: [PATCH 53/56] Update index.rst --- doc/source/overview/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst index b2fc88d0a..3e50b373e 100644 --- a/doc/source/overview/index.rst +++ b/doc/source/overview/index.rst @@ -47,7 +47,7 @@ To try out a library, visit one of these links: If you want to create, develop, or contribute to a PyAnsys library, visit these links: -* `About the PyAnsys Project `_ +* `PyAnsys Developer's Guide `_ * `PyAnsys Documentation Theme `_ * `gRPC Hello-world Example `_ * `Material Example Data `_ From 0a3ff44fc7a6b30356746aae122d90795fd8d971 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 29 Sep 2021 19:24:22 -0400 Subject: [PATCH 54/56] Update index.rst --- doc/source/overview/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst index 3e50b373e..a2c15d1f7 100644 --- a/doc/source/overview/index.rst +++ b/doc/source/overview/index.rst @@ -47,7 +47,7 @@ To try out a library, visit one of these links: If you want to create, develop, or contribute to a PyAnsys library, visit these links: -* `PyAnsys Developer's Guide `_ +* `PyAnsys Project Developer's Guide `_ * `PyAnsys Documentation Theme `_ * `gRPC Hello-world Example `_ * `Material Example Data `_ From 22c2b365b5679dd45cb3adfa6dcd5977317bebe3 Mon Sep 17 00:00:00 2001 From: Alex Kaszynski Date: Wed, 29 Sep 2021 19:23:33 -0600 Subject: [PATCH 55/56] fix links --- doc/source/coding_style/best_practices.rst | 2 +- doc/source/library_description/ci_cd.rst | 10 ++++++---- doc/source/library_description/packaging.rst | 2 ++ doc/source/overview/administration.rst | 1 + doc/source/overview/contributing.rst | 2 +- 5 files changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/source/coding_style/best_practices.rst b/doc/source/coding_style/best_practices.rst index 77c9c5e75..c2e730ea4 100644 --- a/doc/source/coding_style/best_practices.rst +++ b/doc/source/coding_style/best_practices.rst @@ -1,4 +1,4 @@ -.. _best-practices: +.. _best_practices: Best Practices ============== diff --git a/doc/source/library_description/ci_cd.rst b/doc/source/library_description/ci_cd.rst index 2f6db3447..7bda3be1a 100644 --- a/doc/source/library_description/ci_cd.rst +++ b/doc/source/library_description/ci_cd.rst @@ -1,12 +1,14 @@ -CI/CD Methods -############# +.. _ci_cd: + +CI/CD +##### CI/CD (continuous integration/continuous delivery) is achieved using either public `Azure DevOps -`_ or public +`_ or `GitHub Workflow Actions `_ for unit testing, release builds, and documentation builds. The selected method should also be used for branch protection. -For more information, see `Repository Management`. +For more information, see :ref:`repository_management`. Here are some good examples: diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index 81a7beb9a..67ae4b343 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -1,3 +1,5 @@ +.. _packaging: + Packaging ######### A Python package organizes and structures a Python library, which contains several diff --git a/doc/source/overview/administration.rst b/doc/source/overview/administration.rst index df30186b5..c580b137f 100644 --- a/doc/source/overview/administration.rst +++ b/doc/source/overview/administration.rst @@ -30,6 +30,7 @@ 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: Repository Management and Standards =================================== diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst index c73cb841b..a27efce0a 100644 --- a/doc/source/overview/contributing.rst +++ b/doc/source/overview/contributing.rst @@ -110,4 +110,4 @@ responsibility to ensure that the existing license is compatible and included in the contributed files. You must obtain permission from the original author to relicense the code. -See :ref:`license` for more details. +See :ref:`license_file` for more details. From b6a59476c5ff3397d29e3e71ce8150e59c4f8cc2 Mon Sep 17 00:00:00 2001 From: Alex Kaszynski Date: Wed, 29 Sep 2021 22:26:24 -0600 Subject: [PATCH 56/56] Apply suggestions from code review --- doc/source/coding_style/best_practices.rst | 8 ++--- doc/source/coding_style/flake8.rst | 10 +++--- .../source_organization.rst | 2 +- doc/source/overview/administration.rst | 7 ++-- doc/source/overview/contributing.rst | 3 +- doc/source/overview/dev_practices.rst | 36 +++++++++---------- 6 files changed, 33 insertions(+), 33 deletions(-) diff --git a/doc/source/coding_style/best_practices.rst b/doc/source/coding_style/best_practices.rst index c2e730ea4..0393d33d6 100644 --- a/doc/source/coding_style/best_practices.rst +++ b/doc/source/coding_style/best_practices.rst @@ -99,7 +99,7 @@ Use: You should avoid using wild cards in imports because doing so -can cause confusion on which names are present in the namespaces. +can make it difficult to detect undefined names. For more details see `Python Anti-Patterns: using wildcard imports <(https://docs.quantifiedcode.com/python-anti-patterns/maintainability/from_module_import_all_used.html>`_. Avoid: @@ -264,7 +264,7 @@ from PyPi. Class Naming Conventions ~~~~~~~~~~~~~~~~~~~~~~~~ -Use camel case when naming classes. Do not separate words +Use `CamelCase `_ when naming classes. Do not separate words with underscores. .. code:: python @@ -338,7 +338,7 @@ readability. Comments -------- -Because a PyAnsys library generally involve multiple physics domains, +Because a PyAnsys library generally involves multiple physics domains, users reading its source code do not have the same background as the developers who wrote it. This is why it is important for a library to have well commented and documented source code. Comments that @@ -641,7 +641,7 @@ within one single code block. e = self.validate_something(a, b, d) -Aside from the lack of comments, this complex nested validation method +Aside from the lack of comments, this complex method is difficult to debug and validate with unit testing. It would be far better to implement more validation methods and join conditional blocks. diff --git a/doc/source/coding_style/flake8.rst b/doc/source/coding_style/flake8.rst index 50bc8bd5c..6b75620f2 100644 --- a/doc/source/coding_style/flake8.rst +++ b/doc/source/coding_style/flake8.rst @@ -2,9 +2,9 @@ Style Guide Enforcement ======================= -The following sections describe the use of flake8 for `PEP8`_ style +The following sections describe the use of `Flake8`_ for `PEP8`_ style enforcement and the minimum standards expected. PyAnsys libraries -are to be consistent with these guidelines. +are expected to be consistent with these guidelines. .. _PEP8: https://www.python.org/dev/peps/pep-0008/ @@ -127,8 +127,8 @@ PEP8 guidelines requires mininmal manual effort. Minimum Standards ~~~~~~~~~~~~~~~~~ -Descriptions follow of the code style standards expected in the minimum set -for a PyAnsys library. +The following section describes the minimum set of code style standards +expected in an PyAnsys library. * `W191`_ - **Indentation contains tabs.** @@ -205,7 +205,7 @@ for a PyAnsys library. * `F403`_ - **'from module import *' used.** - Importing everything from a module should never be done. Importing + Importing using wildcards (``*``) should never be done. Importing modules this way leads to uncertainty and pollutes the code. You cannot know exactly what is being imported and name clashes are common. Import only the modules to be used. diff --git a/doc/source/library_description/source_organization.rst b/doc/source/library_description/source_organization.rst index a14289e7c..cc5b7e547 100644 --- a/doc/source/library_description/source_organization.rst +++ b/doc/source/library_description/source_organization.rst @@ -32,7 +32,7 @@ When using this convention, other namespace packages can use the >>> from ansys.mapdl import reader as pymapdl_reader -**Note** +.. note:: Do not include ``__init__.py`` in first-level and second-level directories. If ``__init__.py`` is included in these levels, diff --git a/doc/source/overview/administration.rst b/doc/source/overview/administration.rst index c580b137f..9599bacd8 100644 --- a/doc/source/overview/administration.rst +++ b/doc/source/overview/administration.rst @@ -19,7 +19,7 @@ Should you choose to copy and include any PyAnsys project source uses, to make your library suitable for commercial use, you need only a copy of the original PyAnsys MIT license in the reused code. -To view this license, see the `LICENSE` file in the root directory +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 of every PyAnsys library. @@ -66,9 +66,10 @@ possible: * **Patch** version when you make backwards compatible bug fixes. One exception exists. MAJOR versions are not expected to be regularly -released with any incompatible API changes. They are only expected to +released when any incompatible API changes are made. They are only expected to be released with major, globally-breaking API changes. This matches the -versioning for the "big three": `NumPy`_, `SciPy`_, and `pandas`_. +versioning methodology for the "big three" data science python libraries: `NumPy`_, +`SciPy`_, and `pandas`_. .. _Semantic Versioning: https://semver.org/ .. _NumPy: https://numpy.org/ diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst index a27efce0a..65e1af1e8 100644 --- a/doc/source/overview/contributing.rst +++ b/doc/source/overview/contributing.rst @@ -42,14 +42,13 @@ provide feedback. Reporting Bugs -------------- If you encounter a bug or your workflow crashes while using a PyAnsys -library, please create an issue on the `issues`_ page for the respective +library, please create an issue on the issues page of the respective PyAnsys library and tag it with an appropriate label so that it can be promptly addressed. When reporting an issue, be as descriptive as possible so that the issue can be reproduced. Whenever possible, provide a traceback, screenshot, and sample files to help us address the issue. -.. _issues: Issues ------ diff --git a/doc/source/overview/dev_practices.rst b/doc/source/overview/dev_practices.rst index fff71474b..039c1a175 100644 --- a/doc/source/overview/dev_practices.rst +++ b/doc/source/overview/dev_practices.rst @@ -13,7 +13,7 @@ General Development Procedures To submit new code to a PyAnsys, first `fork `_ the repository (for example `PyMAPDL `_) -and then clone the forked repository to your computer. Next, create a new branch based on the +and then clone the forked repository to your local environment. Next, create a new branch based on the `Branch Naming Conventions Section <#branch-naming-conventions>`__ in your local repository. @@ -80,27 +80,27 @@ features without sacrificing stability and closely follows the Descriptions follow for the main features of the branching model. -- The `main` branch is the main development branch. All features, +- The `main` branch is the primary development branch. All features, patches, and other branches should be merged here. While all pull requests (PRs) should pass all applicable CI (Continuous Integration) checks, this branch might be functionally unstable if changes have introduced unintended side-effects or bugs that were not caught through unit testing. - There will be one or many `release/` branches based on minor - releases (for example, `release/0.2`) that contain a stable version - of the code base that is also reflected on PyPi. Hotfixes from + releases (for example, ``release/0.2``) that contain a stable version + of the code base that is also reflected on PyPI. Hotfixes from `fix/` branches should be merged both to main and to these branches. When creating a new patch release is necessary, these - release branches will have their `__version__.py` updated and be - tagged with a patched semantic version (for example, `0.2.1`). This + release branches will have their ``__version__.py`` updated and be + tagged with a patched semantic version (for example, ``0.2.1``). This triggers CI to push to PyPi and allow us to rapidly push hotfixes for past versions without having to worry about untested features. -- When a minor release candidate is ready, a new `release` branch will - be created from `main` with the next incremented minor version - (for example, `release/0.2`), This `release` branch will be thoroughly - tested. When deemed stable, it will be tagged with the version (`0.2.0` - in this case) and merged with `main` if any changes were pushed to it. - Feature development then continues on `main` and any hotfixes will now +- When a minor release candidate is ready, a new ``release`` branch will + be created from ``main`` with the next incremented minor version + (for example, ``release/0.2``), This ``release`` branch will be thoroughly + tested. When deemed stable, it will be tagged with the version (``0.2.0`` + in this case) and merged with ``main`` if any changes were pushed to it. + Feature development then continues on ``main`` and any hotfixes will now be merged with this release. Older release branches should not be deleted so they can be patched as needed. @@ -114,7 +114,7 @@ Major and Minor Procedures follow for major and minor releases. #. Create a new branch from the `main` branch with name - `release/MAJOR.MINOR`(for example, `release/0.2`). + ``release/MAJOR.MINOR`` (for example, ``release/0.2``). #. Locally run all tests as outlined in :ref:`testing` and ensure all are passing. @@ -135,12 +135,12 @@ Procedures follow for major and minor releases. #. Update the version numbers in ``ansys///_version.py`` and commit it. Push the branch to GitHub and create a new PR for this release that merges - it to `main`. Development to `main` should be limited while + it to ``main``. Development to ``main`` should be limited while effort is focused on the release. #. The community and Ansys developers must now functionally test the new release. It is best to locally install this branch and use it in - production. Any bugsidentified should have their hotfixes pushed to + production. Any bugs identified should have their hotfixes pushed to this release branch. #. When the branch is deemed as stable for public release, the PR ismerged @@ -155,13 +155,13 @@ Procedures follow for major and minor releases. git push origin --tags #. Create a list of all changes for the release. It is often helpful - to see the `GitHub's compare feature`_ differences from - the last tag and the `main` branch. Be sure to acknowledge new + to see the differences from the last tag and the ``main`` branch + using `GitHub's compare feature`_ tool. Be sure to acknowledge new contributors by their GitHub username and place mentions where appropriate if a specific contributor is to be thanked for a new feature. -#. Place your release notes from step 8 in the release section with GitHub. See +#. Place your release notes from the previous in the release section within the GitHub repository. See `GitHub Releases`_ .. _GitHub Releases: https://docs.github.com/en/github/administering-a-repository/releasing-projects-on-github/managing-releases-in-a-repository