docutils reports an error rendering view docstring when the first line is not empty

[Manlio Perillo]

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.

[Tim Graham]

Confirmed the patch fixes the issue, although it crashes for some tests with ValueError: min() arg is an empty sequence.

[Simon Charette]

We should probably just switch to inspect.cleandoc as ​it implements the algorithm ​defined in PEP257.

[Manlio Perillo]

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.

[Tapasweni Pathak]

Hello folks: Can I PR?

[Hasan Ramezani]

I can not reproduce on:

• Python=3.7
• django=master
• docutils=0.15.2

@Manlio Perillo, Could you please help me? I am wrong?

[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.

[Baptiste Mispelon]

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.

​PR here

[Mariusz Felisiak <felisiak.mariusz@…>]

In f47ba7e:

Fixed #30255 -- Fixed admindocs errors when rendering docstrings without leading newlines.

Used inspect.cleandoc() which implements PEP-257 instead of an internal
hook.