#25263: How closely we should adhere to PEP 257
-------------------------------------+-------------------------------------
Reporter: Samuel Bishop | Owner: nobody
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
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>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/django-updates/01070198390ca96c-58787501-705a-47c9-8c81-daa9e4527e99-000000%40eu-central-1.amazonses.com.
