-
Notifications
You must be signed in to change notification settings - Fork 126
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docstring formatting #344
Comments
Decoupled from pull request. Low priority item to discuss code formatting guidelines. If a decision in favor of |
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 Hope that helps. 😉 |
Code styleI'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 Docstring styleI 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. |
I've tagged 3 PR with |
About the docstring/doc styles, i've found those projects that could be useful: |
about documentation:
about docstrings: |
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)
The text was updated successfully, but these errors were encountered: