Python-coding-guidelines.md

@@ -13,9 +13,7 @@ Correct:
 
 ```python
 # Aligned with opening delimiter.
-
 foo = long_function_name(var_one, var_two,
-
                          var_three, var_four)
 ```
 
@@ -23,38 +21,26 @@ foo = long_function_name(var_one, var_two,
 
 ```python
 def long_function_name(
-
         var_one, var_two, var_three,
-
         var_four):
-
     print(var_one)
 
 # Hanging indents should add a level.
-
 foo = long_function_name(
-
     var_one, var_two,
-
     var_three, var_four)
 ```
 
 Wrong:
 ```python
 # Arguments on first line forbidden when not using vertical alignment.
-
 foo = long_function_name(var_one, var_two,
-
     var_three, var_four)
 
 # Further indentation required as indentation is not distinguishable.
-
 def long_function_name(
-
     var_one, var_two, var_three,
-
     var_four):
-
     print(var_one)
 ```
 
@@ -100,17 +86,14 @@ For flowing long blocks of text with fewer structural restrictions (docstrings o
 
 ### A Line Should Break Before a Binary Operator?
 
-`# easy to match operators with operands`
-
-`income = (gross_wages`
-
-`          + taxable_interest`
-
-`          + (dividends - qualified_dividends)`
-
-`          - ira_deduction`
-
-`          - student_loan_interest)`
+```python
+# easy to match operators with operands
+income = (gross_wages
+          + taxable_interest
+          + (dividends - qualified_dividends)
+          - ira_deduction
+          - student_loan_interest)
+```
 
 ### Blank lines
 
@@ -204,11 +187,11 @@ The documentation will follow the (numpy convention )\[<https://numpydoc.readthe
 
 A one-line summary that does not use variable names or the function name, e.g.
 
-`def add(a, b):`
-
-`   """The sum of two numbers.`
-
-`   """`
+```python
+def add(a, b):
+   """The sum of two numbers.
+   """
+```
 
 #### Extended Summary
 
@@ -218,37 +201,29 @@ A few sentences giving an extended description. This section should be used to c
 
 Description of the function arguments, keywords and their respective types.
 
-`Parameters`
-
-`----------`
-
-`x : type`
-
-`    Description of parameter x.`
-
-`y`
-
-`    Description of parameter y (with type not specified).`
+```python
+Parameters
+----------
+x : type
+    Description of parameter x.
+y
+    Description of parameter y (with type not specified).
+```
 
 Enclose variables in single backticks. The colon must be preceded by a space, or omitted if the type is absent.
 
 For the parameter types, be as precise as possible. Below are a few examples of parameters and their types.
 
-`Parameters`
-
-`----------`
-
-`filename : str`
-
-`copy : bool`
-
-`dtype : data-type`
-
-`iterable : iterable object`
-
-`shape : int or tuple of int`
-
-`files : list of str`
+```python
+Parameters
+----------
+filename : str
+copy : bool
+dtype : data-type
+iterable : iterable object
+shape : int or tuple of int
+files : list of str
+```
 
 If it is not necessary to specify a keyword argument, use optional :
 
@@ -258,25 +233,23 @@ If it is not necessary to specify a keyword argument, use optional :
 
 Explanation of the returned values and their types. Similar to the [<span dir="">Parameters</span>](https://numpydoc.readthedocs.io/en/latest/format.html#params) section, except the name of each return value is optional. The type of each return value is always required:
 
-`Returns`
-
-`-------`
-
-`int`
-
-`    Description of anonymous integer return value.`
+```python
+Returns
+-------
+int
+    Description of anonymous integer return value.
+```
 
 #### Yields
 
 Explanation of the yielded values and their types. This is relevant to generators only. Similar to the [<span dir="">Returns</span>](https://numpydoc.readthedocs.io/en/latest/format.html#returns) section in that the name of each value is optional, but the type of each value is always required:
 
-`Yields`
-
-`------`
-
-`int`
-
-`    Description of the anonymous integer return value.`
+```python
+Yields
+------
+int
+    Description of the anonymous integer return value.
+```
 
 #### 
 
@@ -284,19 +257,20 @@ Explanation of the yielded values and their types. This is relevant to generator
 
 An optional section that provides additional information about the code, possibly including a discussion of the algorithm.
 
-`Notes`
-
-`-----`
-
-`The FFT is a fast implementation of the discrete Fourier transform`
+```python
+Notes
+-----
+The FFT is a fast implementation of the discrete Fourier transform
+```
 
 #### Hinting
 
 All function parameters and returned values types should be hinted : 
 
-`def greeting(name: str) -> str:`
-
-`    return 'Hello ' + name`
+```python
+def greeting(name: str) -> str:
+    return 'Hello ' + name
+```
 
 ### Documenting classes
 
@@ -304,17 +278,14 @@ Use the same sections as outlined above (all except Returns are applicable). The
 
 An Attributes section, located below the Parameters section, may be used to describe non-method attributes of the class:
 
-`An AtAttributes`
-
-`----------`
-
-`x : float`
-
-`    The X coordinate.`
-
-`y : float`
-
-`    The Y coordinate.`
+```python
+Attributes
+----------
+x : float
+    The X coordinate.
+y : float
+    The Y coordinate.
+```
 
 ## Naming Conventions