[docs] Which style of docstrings to use?

[sbellem]

I would like to help in with the documentation of the code, and noticed different styles being used.

In some places it's the normal standard docstrings, as in:

def binaryagreement(sid, ...):
    '''Binary consensus ...

    :param sid: session identifier
    '''

while in other places it seems to be the NumPy style such as in:

def reliablebroadcast(sid, pid, ...):
    """Reliable broadcast

    Args
    ----
    pid : 0 <= pid < N

    """

More generally, as far as I know there are three possible approaches:

• standard rst
• google style
• numpy style

The google and numpy styles are available via the sphinx.ext.napoleon module.

Assuming that help is welcomed, then if a style is chosen I could help with setting up the documentation boilerplate, etc such that some documentation could be hosted on readthedocs for instance, or wherever you wish.

[amiller]

Help is most definitely welcomed, thank you being here and what you've done so far! Let's do standard docstrings as I don't have either "domain-specific" or "legacy" reasons to use something different.

[amiller]

I'm optimistically assuming you'll agree with this, and closing it as "decision made." Feel free to reopen if we need to consider anything else before choosing to adopt it. Maybe a separate issue will be needed to ensure existing documentation if useful is converted over.