[Django] #30255: docutils reports an error when the first line in a docstring is not empty
Django
---------------------------------------------+------------------------
Reporter: Manlio Perillo | Owner: nobody
Type: Uncategorized | Status: new
Component: contrib.admindocs | Version: 2.1
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
---------------------------------------------+------------------------
Currently admindoc works correctly only with docstrings where the first
line is empty, and all Django docstrings are formatted in this way.
However usually the docstring text starts at the first line, e.g.:
{{{
def test():
"""test tests something.
"""
}}}
and this cause an error:
{{{
Error in "default-role" directive:
no content permitted.
.. default-role:: cmsreference
}}}
The culprit is this code in `trim_docstring`:
{{{
indent = min(len(line) - len(line.lstrip()) for line in lines if
line.lstrip())
}}}
The problem is that the indentation of the first line is 0.
The solution is to skip the first line:
{{{
indent = min(len(line) - len(line.lstrip()) for line in lines[1:] if
line.lstrip())
}}}
Thanks.
--
Ticket URL: <https://code.djangoproject.com/ticket/30255>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
not empty
-----------------------------------+------------------------------------
Reporter: Manlio Perillo | Owner: nobody
Component: contrib.admindocs | Version: 2.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tim Graham):
* type: Uncategorized => Bug
* stage: Unreviewed => Accepted
Comment:
Confirmed the patch fixes the issue, although it crashes for some tests
with `ValueError: min() arg is an empty sequence`.
--
Ticket URL: <https://code.djangoproject.com/ticket/30255#comment:1>
Django
not empty
-----------------------------------+------------------------------------
Component: contrib.admindocs | Version: 2.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Simon Charette):
We should probably just switch to `inspect.cleandoc` as
[https://docs.python.org/3/library/inspect.html#inspect.cleandoc it
implements] the algorithm [https://www.python.org/dev/peps/pep-0257
/#handling-docstring-indentation defined in PEP257].
--
Ticket URL: <https://code.djangoproject.com/ticket/30255#comment:2>
Django
not empty
-----------------------------------+------------------------------------
Component: contrib.admindocs | Version: 2.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Manlio Perillo):
Replying to [comment:1 Tim Graham]:
> Confirmed the patch fixes the issue, although it crashes for some tests
with `ValueError: min() arg is an empty sequence`.
Yes, I also found it yesterday. The simple solution is:
{{{
indent = min((len(line) - len(line.lstrip()) for line in lines[1:] if
line.lstrip()), default=0)
}}}
The `default` argument was added in Python 3.4, so it is safe to use in
Django.
--
Ticket URL: <https://code.djangoproject.com/ticket/30255#comment:3>
Django
not empty
-----------------------------------+------------------------------------
Component: contrib.admindocs | Version: 2.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by tapaswenipathak):
Hello folks: Can I PR?
--
Ticket URL: <https://code.djangoproject.com/ticket/30255#comment:4>
Django
not empty
Reporter: Manlio Perillo | Owner: Hasan
| Ramezani
Type: Bug | Status: assigned
Component: contrib.admindocs | Version: 2.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Hasan Ramezani):
* owner: nobody => Hasan Ramezani
* status: new => assigned
Comment:
I can not reproduce on:
* Python=3.7
* django=master
* docutils=0.15.2
@Manlio Perillo, Could you please help me? I am wrong?
--
Ticket URL: <https://code.djangoproject.com/ticket/30255#comment:5>
Django
not empty
-------------------------------------+-------------------------------------
Reporter: Manlio Perillo | Owner: Hasan
| Ramezani
Type: Bug | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Markus Zapke-Gründemann):
* cc: Markus Zapke-Gründemann (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/30255#comment:6>
Django
not empty
-------------------------------------+-------------------------------------
Reporter: Manlio Perillo | Owner: Hasan
| Ramezani
Type: Bug | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Hasan Ramezani):
@Manlio Perillo,
I couldn't reproduce this bug.
Could you please provide more information about this bug?
Python version, docutils version?
It would be good to have a model definition or test case.
Thanks.
--
Ticket URL: <https://code.djangoproject.com/ticket/30255#comment:7>
Django
not empty
-------------------------------------+-------------------------------------
Reporter: Manlio Perillo | Owner: Hasan
| Ramezani
Type: Bug | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Baptiste Mispelon):
* has_patch: 0 => 1
* version: 2.1 => 3.0
Comment:
After a bit of trial and error, I finally managed to reproduce the issue
on current master with an up-to-date version of `docutils`.
The trick was to use a docstring like this: `"firstline\n\n second
line"` and not the one mentioned in the original report.
I took Simon's suggestion from comment 2 and removed `trim_docstring` in
favor of `inspect.cleandoc` and it fixes the issue.
[https://github.com/django/django/pull/12155 PR here]
--
Ticket URL: <https://code.djangoproject.com/ticket/30255#comment:8>
Django
not empty
-------------------------------------+-------------------------------------
| Mispelon
Type: Bug | Status: assigned
Component: contrib.admindocs | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by felixxm):
* owner: Hasan Ramezani => Baptiste Mispelon
* version: 3.0 => master
--
Ticket URL: <https://code.djangoproject.com/ticket/30255#comment:9>
Django
not empty
-------------------------------------+-------------------------------------
Reporter: Manlio Perillo | Owner: Baptiste
| Mispelon
Component: contrib.admindocs | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak <felisiak.mariusz@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"f47ba7e78033f39742c3bf491e9b15365cefd0db" f47ba7e]:
{{{
#!CommitTicketReference repository=""
revision="f47ba7e78033f39742c3bf491e9b15365cefd0db"
Fixed #30255 -- Fixed admindocs errors when rendering docstrings without
leading newlines.
Used inspect.cleandoc() which implements PEP-257 instead of an internal
hook.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30255#comment:10>