Standard docstring formatting conventions proposal

[jGaboardi]

Standard docstring formatting conventions proposal

0. Based on numpy.
1. Summary starts directly after triple quotes on first line.
2. Empty line between all sections.
3. Valid sections are documented here.
4. If the docstring is a single-line summary, put triple quotes on that line.
5. Variables should be returned whenever possible to aid in clarity and documentation.
6. Enforce proper spelling, grammar, and punctuation.
7. Add type hinting where appropriate.
8. Elements within the Parameters and Returns section should be in the following format:

   <empty line>
   <Section>
   <parameter/variable name><single space><:><single space><type>
   <four-space indent><description>
   <parameter/variable name><single space><:><single space><type>
   <four-space indent><description>
   <empty line>
   <Section>
   

Basic example

def main_func(arg1, arg2):
    """Perform the main function calculation.
    
    Parameters
    ----------
    arg1 : list
        Some values of data.
    arg2 : int
        Some multiplier.
    
    Returns
    -------
    result : list
        Some transformed values of data.
    
    Notes
    -----
    This is a sample equation within a docstring:
    
    .. math::
        
       \displaystyle E = mc^2
        
    See also
    --------
    some.other.Class
    
    Examples
    --------
    Call ``main_func()`` with the following parameters.
    
    >>> main_func([3, 4], 2)
    [6, 8]
    
    """
    
    def helper_func(x: int) -> int:
        """Helper for calculating X."""
        new_x = x*arg2
        return new_x
    
    result = []
    for v in arg1:
        result.append(helper_func(v))
    
    return result

[jGaboardi]

The @pysal/devs team voted in favor of the standard in the May meeting.

[jGaboardi]

@sjsrey @ljwolf I would like to create a new project board for keeping track of progress, etc. on this. Where would it best reside: pysal/pysal, pysal/libpysal, some other repo, or no other repo?

[jGaboardi]

Also need to update:

• CONTRIBUTING.md
• GitHub Standard Operating Procedures
• Getting Started: For developers

[sjsrey]

pysal/pysal makes sense to me

[slumnitz]

Thank you for initiating for bettering documentation @jGaboardi!
I'd like to double check, the official NumPy example does not contain lines between different Parameters,but only between section headers Parameters, Returns, ..., to keep the documentation compact. I would vouch for not including these extra lines, as documentation for functions with many parameters could get very lengthy/ easy to loose sight of parameter options. What do you think and could this be optional potentially?

[jGaboardi]

@slumnitz Yes, you are correct. My example does not exactly conform to numpy's. Thanks for pointing this out. I will update the example and review the work I am currently doing in libpysal.

[jGaboardi]

An automated tool for numpy-style docstring reformatting to keep an eye on from Matthias Bussonnier: see tweet