Docstring formatting
strobeflash opened this issue · comments
Formatting guidelines would be good too
As far as I'm aware we currently have neither code nor doc formatting guidelines, but these would definitely be good to have. For code we might want to switch to black at some point (I'm currently using the PyCharm formatter defaults), but for docs we probably just need to agree on something and stick to that. There's the default rst style, numpy and the google style. A comparison of the three can be found further down the napoleon doc page. We already enabled that Sphinx plugin so any of the three styles should work. Personally, I guess I'd prefer the Google style for parameters and the like as it requires the least amount of superfluous formatting and is nicely readable on a screen that is more wide than tall. 😉 @C4ptainCrunch @tomschr opinions?
Originally posted by @N-Coder in #340 (comment)
Decoupled from pull request.
Low priority item to discuss code formatting guidelines. If a decision in favor of black is made, the recommended strategy is to do it in one massive commit and then use .git-blame-ignore-revs, that is natively supported by github.
As far as I know, code formatting can be done with black and other tools. I've integrated it myself as a tox target in another project. This is quite straightforward.
Depending on your level of dedication to code formatting, you can integrate it as a GH Action, for example, for every pull request. That would make it not a one-time thing, but it will remind all developers about it (for better or worse).
Regarding doc strings, there is docformatter which checks against PEP257. This is only a rudimentary check for correct indentation. It doesn't check if you omitted an argument in your docstrings etc.
If you really want to test if the docstring contains a description of all arguments of the function signature (I think you should), you have to write a more advanced test. I've done in in another project and integrated it in file test_docstrings.py. It checks for RST style docstrings, but I assume it can be changed for any style.
Hope that helps. 😉
Code style
I'm all in for using Black. The only thing that has prevented me from applying it is that we have a lot or PR open and that il will create a huge mess of merge conflicts. Maybe we could schedule the big reformat just before 0.8 ?
To enforce it, i'm using pre-commit in a lot of projects and it works well :)
Docstring style
I really don't have an opinion on this unless that having something consistent is nice (and even nicer if we can auto-format and auto-check in)
EDIT: the choice of napoleon is also quite old and predates the existence of typing annotations so maybe we could have a look at what modern alternatives exists now for the auto-documentation of classes and functions.
The PR count seems quite low -- only 4 open within the last year -- so maybe the current set of merge conflicts is pretty low. The velocity improvements from pre-commit + black would be quite worth any mild disruption. As someone new looking at this project from the outside, there is already a lot tied up in 0.8 so not that associating more with it is worthwhile.
The PR count seems quite low -- only 4 open within the last year -- so maybe the current set of merge conflicts is pretty low.
I've tagged 3 PR with merge-before-black that i think we should try to merge before making huge changes. Let's wait until Monday 11th and if by then some are not merged, we still move forward.
About the docstring/doc styles, i've found those projects that could be useful:
about documentation:
according to https://docs.restructuredtext.net/articles/linter.html, there are two recommended advanced rst checkers, doc8 and rstcheck. I tried both and they seem to report completely different things, rstcheck is arguably more useful.
strobe@tachikoma ~/g/i/doc (main) [1]> doc8 *rst
Scanning...
Validating...
timezone.rst:4: D001 Line too long
timezone.rst:6: D001 Line too long
timezone.rst:42: D001 Line too long
...
timezone.rst:155: D001 Line too long
timezone.rst:209: D005 No newline at end of file
========
Total files scanned = 5
Total files ignored = 0
Total accumulated errors = 23
Detailed error counts:
- doc8.checks.CheckCarriageReturn = 0
- doc8.checks.CheckIndentationNoTab = 0
- doc8.checks.CheckMaxLineLength = 22
- doc8.checks.CheckNewlineEndOfFile = 1
- doc8.checks.CheckTrailingWhitespace = 0
- doc8.checks.CheckValidity = 0
strobe@tachikoma ~/g/i/doc (main) [1]> rstcheck *rst
advanced.rst:67: (ERROR/3) (python) positional argument follows keyword argument
advanced.rst:22: (INFO/1) No role entry for "class" in module "docutils.parsers.rst.languages.en".
advanced.rst:22: (ERROR/3) Unknown interpreted text role "class".
...
advanced.rst:81: (INFO/1) No directive entry for "autoclass" in module "docutils.parsers.rst.languages.en".
advanced.rst:81: (ERROR/3) Unknown directive type "autoclass".
advanced.rst:84: (INFO/1) No directive entry for "autoclass" in module "docutils.parsers.rst.languages.en".
advanced.rst:84: (ERROR/3) Unknown directive type "autoclass".
advanced.rst:1: (INFO/1) Hyperlink target "advanced" is not referenced.
advanced.rst:11: (INFO/1) Hyperlink target "custom-property" is not referenced.
index.rst:10: (INFO/1) No role entry for "ref" in module "docutils.parsers.rst.languages.en".
index.rst:10: (ERROR/3) Unknown interpreted text role "ref".
index.rst:22: (INFO/1) No directive entry for "toctree" in module "docutils.parsers.rst.languages.en".
index.rst:22: (ERROR/3) Unknown directive type "toctree".
index.rst:35: (INFO/1) No directive entry for "toctree" in module "docutils.parsers.rst.languages.en".
index.rst:35: (ERROR/3) Unknown directive type "toctree".
index.rst:52: (INFO/1) No directive entry for "toctree" in module "docutils.parsers.rst.languages.en".
index.rst:52: (ERROR/3) Unknown directive type "toctree".
index.rst:66: (INFO/1) No directive entry for "toctree" in module "docutils.parsers.rst.languages.en".
index.rst:66: (ERROR/3) Unknown directive type "toctree".
index.rst:76: (INFO/1) No role entry for "ref" in module "docutils.parsers.rst.languages.en".
index.rst:76: (ERROR/3) Unknown interpreted text role "ref".
index.rst:77: (INFO/1) No role entry for "ref" in module "docutils.parsers.rst.languages.en".
index.rst:77: (ERROR/3) Unknown interpreted text role "ref".
index.rst:4: (ERROR/3) Undefined substitution referenced: "version".
Error! Issues detected.
about docstrings:
the changes by docformatter seem sensible and pydocstyle helps with formatting too. additionally i found https://github.com/terrencepreilly/darglint, which also checks for completeness of parameters and return values. could make a good combo.