Update docstrings to Numpy style #316
Conversation
| @@ -36,7 +37,15 @@ def __call__(self, func): | |||
| class staticlabel(label): | |||
| """A label decorator for staticmethods. | |||
|
|
|||
| Parameters | |||
| ---------- | |||
| label : | |||
| @@ -46,12 +55,28 @@ def __call__(self, func): | |||
| class classlabel(label): | |||
| """A label decorator for classmethods. | |||
|
|
|||
| Parameters | |||
| ---------- | |||
| label : | |||
|
|
||
| Notes | ||
| ----- | ||
|
|
There was a problem hiding this comment.
I don't think there should be a blank line here.
|
|
||
| Parameters | ||
| ---------- | ||
| func : |
| @@ -11,16 +11,17 @@ | |||
|
|
|||
| class label(object): | |||
| """Decorate a :class:`~.FlowProject` class function as a label function. | |||
|
|
|||
There was a problem hiding this comment.
@CryoZEUS Can remove these extra spaces on otherwise blank lines? I recommend configuring your editor to trim trailing whitespace when you save a file.
| @@ -12,6 +12,7 @@ python-tag = py3 | |||
|
|
|||
| [pydocstyle] | |||
| match = template_filters.py | |||
| match = flow/labels.py | |||
There was a problem hiding this comment.
Please verify whether this overrides the previous "match" or if it checks both files. I'm not sure what behavior to expect from specifying it twice. In signac we used a complicated regular expression to match all desired filenames, examples below.
Initially we started with a list of allowed (files):
https://github.com/glotzerlab/signac/blob/e8209473103f562fe89c54bea1f5d1ba82b9632a/setup.cfg#L17-L19
Then later, once most of the code was compliant, we transitioned to a list of disallowed / skipped files:
https://github.com/glotzerlab/signac/blob/5186bb27621a1707b9d7493e14e551fe6426737d/setup.cfg#L17-L25
| For example: | ||
|
|
||
|
|
||
| .. code-block:: python | ||
|
|
||
|
|
||
| class MyProject(FlowProject): | ||
|
|
||
|
|
||
| @label() | ||
| def foo(self, job): | ||
| return True |
There was a problem hiding this comment.
This should be replaced by an Examples block with a doctest-style code snippet. Look at the "Examples" here: https://numpydoc.readthedocs.io/en/latest/format.html
Something like:
Examples
--------
>>> from flow import FlowProject, label
>>> class MyProject(FlowProject):
... @label
... def foo(self, job):
... return True
There was a problem hiding this comment.
Left one more comment in addition to the previous reviews. Also, the numpy docstring guide suggests that the length of docstring lines should be kept to 75 characters to facilitate reading the docstrings in text terminals. Not sure if flake8 can somehow moderate this.
|
|
||
| Notes | ||
| ----- | ||
|
|
It is possible to specify a maximum line length for pydocstyle distinct from the one we use for code. However, I'm not sure if there's much benefit to that; the reasoning in the numpy docstring guide matches the typical reasoning for keeping line lengths to a specific number, and aside from the practical annoyances with having two different line lengths I don't think it actually improves readability. I'll leave it to the reviewers to make a final call, though. |
b-butler
added
blocked
|
We should hold up on this PR until after GSoC, and then someone will need to take over pushing this PR to completion. |
|
this is no longer blocked if someone wants to pick this up |
|
Replaced by #392. |
Description
Converts module docstrings to numpy style.
Motivation and Context
Issue #278
Types of Changes
1The change breaks (or has the potential to break) existing functionality.
Checklist:
If necessary: