[Django] #25263: How closely we should adhere to PEP 257
Django
--------------------------------------+--------------------
Reporter: techdragon | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+--------------------
Currently the documentation contained in Django's source code has many
places where it could be improved, most significantly by having more of
it. In order to help discover undocumented code, I ran PEP 257 on the
entire project. The thousands of warnings were quite a shock and it was
pretty obvious that a pull request for all of the changes would be too
large.
It seemed like a good idea to open this ticket and find out if continuing
to create new tickets and pull requests for more of this kind of
documentation improvement is in line with the overall project code
standards. I'm opening a pull request that contains a partial cleanup of
the existing documentation inside 'django.views'.
--
Ticket URL: <https://code.djangoproject.com/ticket/25263>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: techdragon | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by techdragon):
* needs_better_patch: => 0
* needs_tests: => 0
* needs_docs: => 0
Old description:
> Currently the documentation contained in Django's source code has many
> places where it could be improved, most significantly by having more of
> it. In order to help discover undocumented code, I ran PEP 257 on the
> entire project. The thousands of warnings were quite a shock and it was
> pretty obvious that a pull request for all of the changes would be too
> large.
>
> It seemed like a good idea to open this ticket and find out if continuing
> to create new tickets and pull requests for more of this kind of
> documentation improvement is in line with the overall project code
> standards. I'm opening a pull request that contains a partial cleanup of
> the existing documentation inside 'django.views'.
New description:
Currently the documentation contained in Django's source code has many
places where it could be improved, most significantly by having more of
it. In order to help discover undocumented code, I ran PEP 257 on the
entire project. The thousands of warnings were quite a shock and it was
pretty obvious that a pull request for all of the changes would be too
large.
It seemed like a good idea to open this ticket and find out if continuing
to create new tickets and pull requests for more of this kind of
documentation improvement is in line with the overall project code
standards. I'm opening a pull request that contains a partial cleanup of
the existing documentation inside 'django.views'.
https://github.com/django/django/pull/5131
--
--
Ticket URL: <https://code.djangoproject.com/ticket/25263#comment:1>
Django
Reporter: techdragon | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by claudep):
I think we have already many code quality checks with Flake8. Are those
conventions really adding value or is this just a trend to adhere to more
conventions? Frankly, the important thing for me is to have documentation.
Then if we add newlines or not for single line comments and such things
look more and more like bikeshedding for me. </rant>
--
Ticket URL: <https://code.djangoproject.com/ticket/25263#comment:2>
Django
Reporter: techdragon | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by akaariai):
I agree with claudep. The idea is that you have clean and well structured
code so that it is easy to maintain. But there is a point after which the
maintenance burden of all the rules is more than what we get in return. At
this point I think we shouldn't add more rules, at least not without
considering carefully if the new rules really give us enough in return.
--
Ticket URL: <https://code.djangoproject.com/ticket/25263#comment:3>
Django
Reporter: techdragon | Owner: nobody
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timgraham):
* status: new => closed
* resolution: => wontfix
Comment:
I agree with what has already been said.
--
Ticket URL: <https://code.djangoproject.com/ticket/25263#comment:4>
Django
Reporter: techdragon | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by techdragon):
* status: closed => new
* resolution: wontfix =>
Comment:
I'm reopening it since I didn't get a chance to comment on the criticism
before it was closed.
It's worth considering that some of the things that PEP 257 recommends are
areas beneficial to the level of documentation in the source code.
Checks D100, D101, D102, and D103 all indicate Modules, Classes and
Methods that have no documentation at all.
Others are mainly about consistency and some of them are definitely of
minimal improvement or possibly even detrimental.
The full list is below.
Missing Docstrings
D100 Missing docstring in public module
D101 Missing docstring in public class
D102 Missing docstring in public method
D103 Missing docstring in public function
Whitespace Issues
D200 One-line docstring should fit on one line with quotes
D201 No blank lines allowed before function docstring
D202 No blank lines allowed after function docstring
D203 1 blank line required before class docstring
D204 1 blank line required after class docstring
D205 1 blank line required between summary line and description
D206 Docstring should be indented with spaces, not tabs
D207 Docstring is under-indented
D208 Docstring is over-indented
D209 Multi-line docstring closing quotes should be on a separate line
D210 No whitespaces allowed surrounding docstring text
Quotes Issues
D300 Use “”“triple double quotes”“”
D301 Use r”“” if any backslashes in a docstring
D302 Use u”“” for Unicode docstrings
Docstring Content Issues
D400 First line should end with a period
D401 First line should be in imperative mood
D402 First line should not be the function’s “signature”
--
Ticket URL: <https://code.djangoproject.com/ticket/25263#comment:5>
Django
Reporter: techdragon | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Old description:
> Currently the documentation contained in Django's source code has many
> places where it could be improved, most significantly by having more of
> it. In order to help discover undocumented code, I ran PEP 257 on the
> entire project. The thousands of warnings were quite a shock and it was
> pretty obvious that a pull request for all of the changes would be too
> large.
>
> It seemed like a good idea to open this ticket and find out if continuing
> to create new tickets and pull requests for more of this kind of
> documentation improvement is in line with the overall project code
> standards. I'm opening a pull request that contains a partial cleanup of
> the existing documentation inside 'django.views'.
> https://github.com/django/django/pull/5131
New description:
Currently the documentation contained in Django's source code has many
places where it could be improved, most significantly by having more of
it. In order to help discover undocumented code, I ran
[https://pypi.python.org/pypi/pep257 PEP 257] on the entire project. The
thousands of warnings were quite a shock and it was pretty obvious that a
pull request for all of the changes would be too large.
It seemed like a good idea to open this ticket and find out if continuing
to create new tickets and pull requests for more of this kind of
documentation improvement is in line with the overall project code
standards. I'm opening a pull request that contains a partial cleanup of
the existing documentation inside 'django.views'.
https://github.com/django/django/pull/5131
--
Comment (by timgraham):
Feel free to raise the idea on the DevelopersMailingList. Personally, I
don't think requiring docstrings for everything is needed and I don't care
for whitespace around class docstrings.
--
Ticket URL: <https://code.djangoproject.com/ticket/25263#comment:6>
Django
Reporter: techdragon | Owner: nobody
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by claudep):
* status: new => closed
* resolution: => wontfix
Comment:
Closing until consensus comes from django-dev discussions.
--
Ticket URL: <https://code.djangoproject.com/ticket/25263#comment:7>
Django
Reporter: Samuel Bishop | Owner: nobody
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage:
| Unreviewed
Comment (by Mike Edmunds):
There's now a [https://pypi.org/project/docformatter/ docformatter] tool
available that performs opinionated PEP 257 reformatting of docstrings.
I don't think it would be a good idea, but wanted to make a note here in
case PEP 257 comes up again in the future.
While investigating #36500, I tried running docformatter on the Django
code. It was very disruptive and would require a ''huge amount'' of manual
cleanup. The big problem is that—unlike running black on Python code or
sphinx-lint on reStructuredText—docformatter can't count on a defined
syntax within docstrings. It has some reasonable heuristics, but (e.g.,)
frequently mistakes example code in Django's docstrings for ordinary text
and refills that code as a paragraph. And it struggles with the variety of
parameter-description formats appearing in Django.
My experiments used this docformatter command:
{{{#!shell
docformatter \
--recursive \
--in-place \
--wrap-summaries 79 \
--wrap-descriptions 79 \
--pre-summary-newline \
--close-quotes-on-newline \
django docs extras scripts tests
}}}
Those last two options aren't strictly PEP 257, but seemed a better match
for Django's prevailing docstring style.
--
Ticket URL: <https://code.djangoproject.com/ticket/25263#comment:8>