Opened 6 years ago
Closed 5 years ago
#30255 closed Bug (fixed)
docutils reports an error rendering view docstring when the first line is not empty
Reported by: | Manlio Perillo | Owned by: | Baptiste Mispelon |
---|---|---|---|
Component: | contrib.admindocs | Version: | dev |
Severity: | Normal | Keywords: | |
Cc: | Markus Zapke-Gründemann | Triage Stage: | Accepted |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | no | UI/UX: | no |
Description
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.
Change History (10)
follow-up: 3 comment:1 by , 6 years ago
Summary: | docutils reports an error when the first line in a docstring is not empty → docutils reports an error rendering view docstring when the first line is not empty |
---|---|
Triage Stage: | Unreviewed → Accepted |
Type: | Uncategorized → Bug |
comment:2 by , 6 years ago
We should probably just switch to inspect.cleandoc
as it implements the algorithm defined in PEP257.
comment:3 by , 6 years ago
Replying to 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.
comment:5 by , 5 years ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
I couldn't reproduce it on:
- Python=3.7
- django=master
- docutils=0.15.2
@Manlio Perillo, Could you please help me? I am wrong?
comment:6 by , 5 years ago
Cc: | added |
---|
comment:7 by , 5 years ago
@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.
comment:8 by , 5 years ago
Has patch: | set |
---|---|
Version: | 2.1 → 3.0 |
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.
comment:9 by , 5 years ago
Owner: | changed from | to
---|---|
Version: | 3.0 → master |
Confirmed the patch fixes the issue, although it crashes for some tests with
ValueError: min() arg is an empty sequence
.