Add extra newline in io.BytesIO.seek() to prevent a Sphinx warning

[janlugt]

When generating documentation with Sphinx for one of my projects, I get a warning for documentation inherited from BytesIO. The code for the class is very simple:

class BlobFile(io.BytesIO):
  pass

my_class.py:docstring of MyClass.seek:7: WARNING: Definition list ends without a blank line; unexpected unindent.

This would be fixed with an extra newline in the documentation for BytesIO.

[the-knights-who-say-ni]

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA).

Recognized GitHub username

We couldn't find a bugs.python.org (b.p.o) account corresponding to the following GitHub usernames:

@janlugt

This might be simply due to a missing "GitHub Name" entry in one's b.p.o account settings. This is necessary for legal reasons before we can look at this contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

You can check yourself to see if the CLA has been received.

Thanks again for the contribution, we look forward to reviewing it!

[janlugt]

CLA has been signed, should be processed by tomorrow.

[akulakov]

Jan: in this PR, the blank line is added in a C source file instead of docs file.

[janlugt]

That's correct, but these chunks of documentation do make it into the class documentation for io.BytesIO, and thus into sphinx-generated documentation for subclasses created from it.

[MaxwellDupre]

Cant hurt

[ghost]

All commit authors signed the Contributor License Agreement.

[bedevere-bot]

Every change to Python requires a NEWS entry.

Please, add it using the blurb_it Web app or the blurb command-line tool.

[MaxwellDupre]

Approved

[bedevere-bot]

Most changes to Python require a NEWS entry.

Please add it using the blurb_it web app or the blurb command-line tool.

[JulienPalard]

At first glance it does not seems to fix the issue (try by simply copying-pasting the docstring to a rst file, but it does not looks like a reStructuredText list even after the newline being added).

But beware: Python docstrings are not intended to be valid reStructuredText, so using autodoc with :inherited-members: with cpython classes as parents is just not supported.

By fixing one, you're opening the path to rewrite all Python docstrings, this is a monumental amount of work that can't be done without first raising the idea on python-ideas@, it getting traction, speaking about it on python-dev@, having PEP 7, PEP 8 and PEP 257 amended... but I personally don't think we'll ever see Sphinx roles in docstrings (who want to see sphinx roles when using help(...) from an interpreter?).

So I'm sadly just closing this PR. But thanks @janlugt for the good intention of fixing something and having taken the time to open a PR, this is greatly appreciated.