#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 django-updates+unsubscr...@googlegroups.com.
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.
