Guideline regarding docstring (+ automatic code formatting?)

[yohplala]

Hi,
Please, as I am working on a PR (and this is likely not the last ;)), I would like to have guidance regarding acceptable formatting for the docstring of the functions.

I can see different formattings for the begining of the docstring. Please, which one should be retained?
(all the remaining of the docstring is the same for all examples, but if you would like to share recommandations / guidelines for the remaining of the docstring, please, do so)

# Choice 1
def my_function(x:int) -> int:
    """One-line description, right after the 3 ", no whitespace.

    Then one blank line, followed by a lengthier description. As much as possible
    not going longer than the 80th column. Then one blank line, then Parameters,
    then Returns...

    Parameters
    x : int
        Description of the input.

    Returns
    int
        Description of the output.
    """

# Choice 2
def my_function(x:int) -> int:
    """ One-line description, right after the 3 ", with whitespace.

    Then one blank line, followed by a lengthier description. As much as possible
    not going longer than the 80th column. Then one blank line, then Parameters,
    then Returns...

    Parameters
    x : int
        Description of the input.

    Returns
    int
        Description of the output.
    """

# Choice 3
def my_function(x:int) -> int:
    """
    One-line description, below the 3 ".

    Then one blank line, followed by a lengthier description. As much as possible
    not going longer than the 80th column. Then one blank line, then Parameters,
    then Returns...

    Parameters
    x : int
        Description of the input.

    Returns
    int
        Description of the output.
    """

Please, which formatting should be followed?

Also, regarding the code formating itself, I can see that some codes use in pre-commit some automatic python code formatter. (black formatter for instance). Do you think we should investigate this? (I had a look at black documentation quickly, and it is stated it does not format comments or docstring, hence my questions above)

Thanks for the feedback!
Bests,

[martindurant]

I believe that in ipython, jupyter or sphinx rendering, all of those variants will look the same, so I wouldn't worry much about it. Generally, we are following numpydoc, full descriptions here.

some codes use in pre-commit some automatic python code formatter. (black formatter for instance). Do you think we should investigate this?

It would be reasonable to require some standard linting (flake8, black, isort) via pre-commit or otherwise. Obviously, implementing this would change most of the function blocks and make all current PRs very hard to merge - so the timing of formatting introduction is very sensitive. The lack of these tools here is a result of this repo being older than most of mine, but still single-handedly maintained.

[yohplala]

Generally, we are following numpydoc, full descriptions here.

Thanks a lot @martindurant , I will do my best to follow them. I have started doing so in the on-going PR #712

so the timing of formatting introduction is very sensitive.

I understand. Let's do this when the opportunity arises... a bit later once current PRs are done with.

[yohplala]

As much as possible taken into account in #712