doc/edit and reorganize best practice info (#43)

* doc/edit and reorganize best practice info

* doc/edit and reorganize best practice info

* doc/edit and reorganize best practice info

* doc/edit and reorganize best practice info

* fix duplicate explicit target name

* Update doc/source/documentation_style/class_documentation.rst

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

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

Author: 3 people

doc/source/documentation_style/coding_style.rst renamed to doc/source/coding_style/beyond_pep8.rst

@@ -1,10 +1,6 @@
-Coding Style and Best Practices
-###############################
-This page provides best practices applicable to the `PyAnsys
-<https://pypi.org/project/pyansys/>`_ project.  The intent is 
-not to repeat coding style documentation but rather to state
-the approach used by the PyAnsys project when there are any
-delineations, clarifications, or additional procedures above and 
+Beyond PEP8
+###########
+This topic describes any delineations, clarifications, or additional procedures above and 
 beyond `PEP8 <https://www.python.org/dev/peps/pep-0008/>`__.
 
 For example, `Stack Overflow Answer <https://stackoverflow.com/questions/2536307>`_ 
@@ -87,7 +83,7 @@ Python, an alternative is to create a custom ``DeprecationError``.
             """Empty init."""
             RuntimeError.__init__(self, message)
 
-You then use this custom ``DeprecationError`` in place of an ``Exception``.
+You can then use this custom ``DeprecationError`` in place of an ``Exception``.
 
 .. code:: python
 
@@ -142,7 +138,7 @@ also be used to perform regression testing to verify that the code is
 executing as expected.
 
 This is an important feature of maintainable documentation as examples
-must always match the API they are documenting. When using `doctest`` 
+must always match the API they are documenting. When using ``doctest`` 
 through ``pytest``, any changes within the API without corresponding 
 changes in the documentation will trigger doctest failures.
 
@@ -270,8 +266,8 @@ example by referencing the key ``icepak``.
 
         """
 
-Useful Features
-~~~~~~~~~~~~~~~
+Useful ``doctest`` Features
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Ellipses for Random Output
 **************************
@@ -299,7 +295,7 @@ To support this, ``doctest`` must be run with the option set to allow ellipses.
 The directive ``# doctest: +SKIP`` can be added to any line of a
 docstring example so that it is not executed in ``doctest-modules``. 
 This is useful for examples that cannot run within ``pytest`` or have 
-side-effects that will affect the other tests if they are run during 
+side effects that will affect the other tests if they are run during 
 the ``doctest`` session.
 
 .. code :: python

doc/source/coding_style/flake8.rst

@@ -2,7 +2,7 @@
 
 Style Guide Enforcement
 =======================
-The following sections describe the use of `Flake8`_ for `PEP8`_ style
+This topic describes the use of `Flake8`_ for `PEP8`_ style
 enforcement and the minimum standards expected. PyAnsys libraries
 are expected to be consistent with these guidelines.
 
@@ -27,7 +27,7 @@ Configuring Flake8
 Flake8 supports configuring a specific set of style rules to
 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
+store the Flake8 configuration in a ``.flake8`` file at the root of the
 repository.
 
 Here is an example of a ``.flake8`` configuration file from a PyAnsys
@@ -44,48 +44,50 @@ library:
     statistics = True
 
 Flake8 has many options that can be set within the configuration file.
-A list of possible options can be found `here <https://flake8.pycqa.org/en/latest/user/options.html>`__.
+For a list and descriptions, see this `Flake8 documentation topic
+<https://flake8.pycqa.org/en/latest/user/options.html>`__.
 
-The above configuration defines the following options:
+The example configuration defines the following options:
 
 - ``exclude``
-    This denotes subdirectories and ``doc/_build``, along with all
+    Denotes subdirectories and ``doc/_build``, along with all
     ``__init__.py`` files to be excluded from the check.
 
 - ``select``
-    This is a sequence of error codes that flake8 will report errors
+    Sequence of error codes that Flake8 will report errors
     for. The set in the above configuration is a basic set of errors to
     check for and is not an exhaustive list.
 
-    A full list of error codes and their descriptions can be found `here <https://flake8.pycqa.org/en/3.9.2/user/error-codes.html>`__.
+    For a full list of error codes and their descriptions, see this `Flake8
+    documentation topic <https://flake8.pycqa.org/en/3.9.2/user/error-codes.html>`__.
 
 - ``count``
-    The total number of errors is printed at the end of the check.
+    Total number of errors to print at the end of the check.
 
 - ``max-complexity``
-    This sets the maximum allowed McCabe complexity value for a block of code.
+    Sets the maximum allowed McCabe complexity value for a block of code.
     The value of 10 was chosen because it is a common default.
 
 - ``max-line-length``
-    This denotes the maximum line length for any one line of code.
+    Denotes the maximum line length for any one line of code.
     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 library is 100.
 
 - ``statistics``
-    This enables the number of occurrences of each error or warning code
+    Number of occurrences of each error or warning code
     to be printed as a report at the end of the check.
 
 
 Running Flake8
 --------------
-First, to install flake8, run:
+First, to install Flake8, run:
 
 .. code::
 
     python -m pip install flake8
 
-Then, flake8 can be run from inside your project directory by executing:
+Then, you can run Flake8 from inside your project directory by executing:
 
 .. code::
 
@@ -95,7 +97,7 @@ 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.
+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 style rules from being merged into the code
 base.
@@ -110,12 +112,12 @@ the formatting tool `black`_.
 
 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
+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``. This can be
+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 <https://black.readthedocs.io/en/stable/integrations/source_version_control.html>`_
 will automatically format the code before committing. This simple way of
@@ -128,7 +130,7 @@ PEP8 guidelines requires minimal manual effort.
 Minimum Standards
 ~~~~~~~~~~~~~~~~~
 The following section describes the minimum set of code style standards
-expected in an PyAnsys library.
+expected in a PyAnsys library.
 
 * `W191`_ - **Indentation contains tabs.**
 
@@ -193,11 +195,11 @@ expected in an PyAnsys library.
 * `E501`_ - **Line too long.**
 
     All code lines should not exceed 100 characters. The
-    `PEP8 line length <https://www.python.org/dev/peps/pep-0008/#maximum-line-length>`_
-    guidelines suggest a maximum line length of 79. Following this limit
+    `PEP8 line length guideline <https://www.python.org/dev/peps/pep-0008/#maximum-line-length>`_
+    suggests a maximum line length of 79. Following this limit
     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.
+    viewing files side by side in code editors.
 
 * `F401`_ - **Module imported but unused.**
 

doc/source/coding_style/index.rst

@@ -4,7 +4,7 @@ Coding Style
 ************
 
 PyAnsys libraries are expected to follow `PEP8`_ and
-be consistent in style and formatting with the "big three"
+be consistent in style and formatting with the 'big three'
 data science libraries: `NumPy`_, `SciPy`_, and `pandas`_.
 
 .. _NumPy: https://numpy.org/
@@ -24,5 +24,6 @@ data science libraries: `NumPy`_, `SciPy`_, and `pandas`_.
    :hidden:
    :maxdepth: 3
 
+   pep8_best_practices
+   beyond_pep8
    flake8
-   best_practices