Skip to content

Commit 270ceff

Browse files
PipKatakaszynskiMaxJPRey
authored
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]>
1 parent 2eff8ef commit 270ceff

File tree

8 files changed

+158
-153
lines changed

8 files changed

+158
-153
lines changed

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

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
1-
Coding Style and Best Practices
2-
###############################
3-
This page provides best practices applicable to the `PyAnsys
4-
<https://pypi.org/project/pyansys/>`_ project. The intent is
5-
not to repeat coding style documentation but rather to state
6-
the approach used by the PyAnsys project when there are any
7-
delineations, clarifications, or additional procedures above and
1+
Beyond PEP8
2+
###########
3+
This topic describes any delineations, clarifications, or additional procedures above and
84
beyond `PEP8 <https://www.python.org/dev/peps/pep-0008/>`__.
95

106
For example, `Stack Overflow Answer <https://stackoverflow.com/questions/2536307>`_
@@ -87,7 +83,7 @@ Python, an alternative is to create a custom ``DeprecationError``.
8783
"""Empty init."""
8884
RuntimeError.__init__(self, message)
8985
90-
You then use this custom ``DeprecationError`` in place of an ``Exception``.
86+
You can then use this custom ``DeprecationError`` in place of an ``Exception``.
9187
9288
.. code:: python
9389
@@ -142,7 +138,7 @@ also be used to perform regression testing to verify that the code is
142138
executing as expected.
143139
144140
This is an important feature of maintainable documentation as examples
145-
must always match the API they are documenting. When using `doctest``
141+
must always match the API they are documenting. When using ``doctest``
146142
through ``pytest``, any changes within the API without corresponding
147143
changes in the documentation will trigger doctest failures.
148144
@@ -270,8 +266,8 @@ example by referencing the key ``icepak``.
270266
271267
"""
272268
273-
Useful Features
274-
~~~~~~~~~~~~~~~
269+
Useful ``doctest`` Features
270+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
275271
276272
Ellipses for Random Output
277273
**************************
@@ -299,7 +295,7 @@ To support this, ``doctest`` must be run with the option set to allow ellipses.
299295
The directive ``# doctest: +SKIP`` can be added to any line of a
300296
docstring example so that it is not executed in ``doctest-modules``.
301297
This is useful for examples that cannot run within ``pytest`` or have
302-
side-effects that will affect the other tests if they are run during
298+
side effects that will affect the other tests if they are run during
303299
the ``doctest`` session.
304300
305301
.. code :: python

doc/source/coding_style/flake8.rst

Lines changed: 22 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Style Guide Enforcement
44
=======================
5-
The following sections describe the use of `Flake8`_ for `PEP8`_ style
5+
This topic describes the use of `Flake8`_ for `PEP8`_ style
66
enforcement and the minimum standards expected. PyAnsys libraries
77
are expected to be consistent with these guidelines.
88

@@ -27,7 +27,7 @@ Configuring Flake8
2727
Flake8 supports configuring a specific set of style rules to
2828
enforce. This configuration can be stored in your library in a
2929
``setup.cfg``, ``tox.ini``, or ``.flake8`` file. PyAnsys libraries
30-
store the flake8 configuration in a ``.flake8`` file at the root of the
30+
store the Flake8 configuration in a ``.flake8`` file at the root of the
3131
repository.
3232

3333
Here is an example of a ``.flake8`` configuration file from a PyAnsys
@@ -44,48 +44,50 @@ library:
4444
statistics = True
4545
4646
Flake8 has many options that can be set within the configuration file.
47-
A list of possible options can be found `here <https://flake8.pycqa.org/en/latest/user/options.html>`__.
47+
For a list and descriptions, see this `Flake8 documentation topic
48+
<https://flake8.pycqa.org/en/latest/user/options.html>`__.
4849

49-
The above configuration defines the following options:
50+
The example configuration defines the following options:
5051

5152
- ``exclude``
52-
This denotes subdirectories and ``doc/_build``, along with all
53+
Denotes subdirectories and ``doc/_build``, along with all
5354
``__init__.py`` files to be excluded from the check.
5455

5556
- ``select``
56-
This is a sequence of error codes that flake8 will report errors
57+
Sequence of error codes that Flake8 will report errors
5758
for. The set in the above configuration is a basic set of errors to
5859
check for and is not an exhaustive list.
5960

60-
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>`__.
61+
For a full list of error codes and their descriptions, see this `Flake8
62+
documentation topic <https://flake8.pycqa.org/en/3.9.2/user/error-codes.html>`__.
6163

6264
- ``count``
63-
The total number of errors is printed at the end of the check.
65+
Total number of errors to print at the end of the check.
6466

6567
- ``max-complexity``
66-
This sets the maximum allowed McCabe complexity value for a block of code.
68+
Sets the maximum allowed McCabe complexity value for a block of code.
6769
The value of 10 was chosen because it is a common default.
6870

6971
- ``max-line-length``
70-
This denotes the maximum line length for any one line of code.
72+
Denotes the maximum line length for any one line of code.
7173
The `PEP8`_ standard advises a maximum line length of 79. Because
7274
this is a bit limiting in some cases, the maximum line length
7375
recommended for a PyAnsys library is 100.
7476

7577
- ``statistics``
76-
This enables the number of occurrences of each error or warning code
78+
Number of occurrences of each error or warning code
7779
to be printed as a report at the end of the check.
7880

7981

8082
Running Flake8
8183
--------------
82-
First, to install flake8, run:
84+
First, to install Flake8, run:
8385

8486
.. code::
8587
8688
python -m pip install flake8
8789
88-
Then, flake8 can be run from inside your project directory by executing:
90+
Then, you can run Flake8 from inside your project directory by executing:
8991

9092
.. code::
9193
@@ -95,7 +97,7 @@ This uses the configuration defined in the ``.flake8`` file to
9597
run the style checks on the appropriate files within the project and
9698
report any errors.
9799

98-
In PyAnsys libraries, flake8 is run as part of the CI/CD for code style.
100+
In PyAnsys libraries, Flake8 is run as part of the CI/CD for code style.
99101
This action is run as a required check on pull requests, preventing
100102
code in violation of style rules from being merged into the code
101103
base.
@@ -110,12 +112,12 @@ the formatting tool `black`_.
110112

111113
On completing a code change, and before committing, `black`_ can be
112114
run to reformat the code, following the PEP8 guidelines enforced through
113-
flake8. This will limit any manual code changes needed to address style
115+
Flake8. This will limit any manual code changes needed to address style
114116
rules.
115117

116118
.. _black: https://black.readthedocs.io/en/stable/
117119

118-
Optionally, it is possible to automate the use of ``black``. This can be
120+
Optionally, it is possible to automate the use of `black`_. This can be
119121
done with the tool `pre-commit`_. Setting up a `pre-commit hook
120122
to run black <https://black.readthedocs.io/en/stable/integrations/source_version_control.html>`_
121123
will automatically format the code before committing. This simple way of
@@ -128,7 +130,7 @@ PEP8 guidelines requires minimal manual effort.
128130
Minimum Standards
129131
~~~~~~~~~~~~~~~~~
130132
The following section describes the minimum set of code style standards
131-
expected in an PyAnsys library.
133+
expected in a PyAnsys library.
132134

133135
* `W191`_ - **Indentation contains tabs.**
134136

@@ -193,11 +195,11 @@ expected in an PyAnsys library.
193195
* `E501`_ - **Line too long.**
194196

195197
All code lines should not exceed 100 characters. The
196-
`PEP8 line length <https://www.python.org/dev/peps/pep-0008/#maximum-line-length>`_
197-
guidelines suggest a maximum line length of 79. Following this limit
198+
`PEP8 line length guideline <https://www.python.org/dev/peps/pep-0008/#maximum-line-length>`_
199+
suggests a maximum line length of 79. Following this limit
198200
is not as necessary today due to modern screen sizes. The suggested maximum
199201
length of 100 can be easier to accommodate and can still support
200-
viewing files side-by-side in code editors.
202+
viewing files side by side in code editors.
201203

202204
* `F401`_ - **Module imported but unused.**
203205

doc/source/coding_style/index.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Coding Style
44
************
55

66
PyAnsys libraries are expected to follow `PEP8`_ and
7-
be consistent in style and formatting with the "big three"
7+
be consistent in style and formatting with the 'big three'
88
data science libraries: `NumPy`_, `SciPy`_, and `pandas`_.
99

1010
.. _NumPy: https://numpy.org/
@@ -24,5 +24,6 @@ data science libraries: `NumPy`_, `SciPy`_, and `pandas`_.
2424
:hidden:
2525
:maxdepth: 3
2626

27+
pep8_best_practices
28+
beyond_pep8
2729
flake8
28-
best_practices

0 commit comments

Comments
 (0)