Python 3.11: "WARNING: Literal block expected; none found"

[hugovk]

Describe the bug

When building docs with enums like this:

.. autoclass:: Transpose
    :members:
    :undoc-members:

Referring to code like this:

class Transpose(IntEnum):
    FLIP_LEFT_RIGHT = 0
    FLIP_TOP_BOTTOM = 1
    ROTATE_90 = 2
    ROTATE_180 = 3
    ROTATE_270 = 4
    TRANSPOSE = 5
    TRANSVERSE = 6

I get no warnings with Python 3.10. But with Python 3.11 I get a warning:

/Users/huvankem/github/Pillow/src/PIL/Image.py:docstring of PIL.Image.Transpose:7: WARNING: Literal block expected; none found.

How to Reproduce

$ git clone https://github.com/python-pillow/Pillow/
$ cd Pillow
$ pip install -e ".[docs]"
$ cd docs
$ python3.11 -m sphinx.cmd.build -b html -W --keep-going . _build/html

Expected behavior

No warnings, like with Python 3.10:

$ python3.10 -m sphinx.cmd.build -b html -W --keep-going . _build/html

Your project

https://github.com/python-pillow/Pillow

Screenshots

OS

macOS 12.3.1 Monterey and Linux 20.04

Python version

Python 3.11.0a7+

Sphinx version

4.5.0

Sphinx extensions

sphinx_copybutton, sphinx_issues, sphinx_removed_in, sphinx.ext.autodoc, sphinx.ext.intersphinx, sphinx.ext.viewcode, sphinxext.opengraph

Extra tools

No response

Additional context

If I add a docstring to the enum the warning goes away:

class Transpose(IntEnum):
    """My docstring"""
    FLIP_LEFT_RIGHT = 0
    FLIP_TOP_BOTTOM = 1
    ROTATE_90 = 2
    ROTATE_180 = 3
    ROTATE_270 = 4
    TRANSPOSE = 5
    TRANSVERSE = 6

Which is probably a good idea anyway, but I wanted to check if this is an intentional change with Python 3.11, something that needs changing in Sphinx to handle 3.11, or (like #10030) a bug in 3.11.

(3.11 enters beta next week, and is set for full release in October.)

[tk0miya]

It seems the document of the enum subclasses has been changed since 3.11. And it's invalid.

$ python3.10
Python 3.10.3 (main, Apr  6 2022, 11:26:01) [Clang 11.0.3 (clang-1103.0.32.62)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import example
>>> print(example.Transpose.__doc__)
An enumeration.
>>>

$ python3.11
Python 3.11.0a7+ (heads/main:ad5e852, May  2 2022, 01:40:38) [Clang 11.0.3 (clang-1103.0.32.62)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import example
>>> print(example.Transpose.__doc__)
A collection of name/value pairs.

Access them by:

- attribute access::

>>> Transpose.FLIP_LEFT_RIGHT
<Transpose.FLIP_LEFT_RIGHT: 0>

- value lookup:

>>> Transpose(0)
<Transpose.FLIP_LEFT_RIGHT: 0>

- name lookup:

>>> Transpose['FLIP_LEFT_RIGHT']
<Transpose.FLIP_LEFT_RIGHT: 0>

Enumerations can be iterated over, and know how many members they have:

>>> len(Transpose)
2

>>> list(Transpose)
[<Transpose.FLIP_LEFT_RIGHT: 0>, <Transpose.FLIP_TOP_BOTTOM: 1>]

Methods can be added to enumerations, and members can have their own
attributes -- see the documentation for details.

>>>

[hugovk]

I'm no longer getting this warning with latest Python 3.11.0b4+ (heads/3.11:0fda874, Jul 22 2022, 20:04:14) [Clang 13.1.6 (clang-1316.0.21.2.5)]:

# example.py
from enum import IntEnum


class Transpose(IntEnum):
    FLIP_LEFT_RIGHT = 0
    FLIP_TOP_BOTTOM = 1
    ROTATE_90 = 2
    ROTATE_180 = 3
    ROTATE_270 = 4
    TRANSPOSE = 5
    TRANSVERSE = 6

The 3.10 output is as before:

Python 3.10.5 (v3.10.5:f377153967, Jun  6 2022, 12:36:10) [Clang 13.0.0 (clang-1300.0.29.30)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
(imported collections, datetime as dt, itertools, math, os, pprint, re, sys, time)
>>> import example
>>> print(example.Transpose.__doc__)
An enumeration.
>>>

But the 3.11 output is now None:

Python 3.11.0b4+ (heads/3.11:0fda874, Jul 22 2022, 20:04:14) [Clang 13.1.6 (clang-1316.0.21.2.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import example
>>> print(example.Transpose.__doc__)
None
>>>

[electric-coder]

@AA-Turner I just came across this issue and tested it as described, it's working after the linked upstream fixes.

I think the issue can be closed as the OP asserted. Tested using:

Python 3.11.3 (tags/v3.11.3:f3909b8, Apr 4 2023, 23:49:59) [MSC v.1934 64 bit (AMD64)] on win32
Sphinx v6.2.1
Windows 10 version 21H2