Search code examples
pythonpython-sphinx

Sphinx raises warnings for class derived from IntEnum - can I do something about it?


As the title says. The warnings are:

docstring of liesel.goose.EpochType.from_bytes:9: WARNING: Inline interpreted text or phrase reference start-string without end-string.
docstring of liesel.goose.EpochType.to_bytes:8: WARNING: Inline interpreted text or phrase reference start-string without end-string.

I am using Sphinx version 7.2.6.

My investigation yielded the following:

The class EpochType is derived from enum.IntEnum. IntEnum is derived partly from int (source code on GitHub).

As far as I can see, the methods from_bytes and to_bytes originate from the corresponding methods on int.

I do not understand why sphinx is throwing this warning and/or what I can do about it.


Solution

  • I ran into this problem too, and @mzjn's explanation seems to be right. A fix to use apostrophes for the opening quotes got merged and will be in the upcoming Python 3.13. release: https://github.com/python/cpython/pull/117847

    I also tried to fix a handful other similar cases of this in the standard library in https://github.com/python/cpython/pull/119231 so hopefully people won't run into it with other classes.

    Until you can switch to Python 3.13, you can probably work around this by writing :inherited-members: int instead of :inherited-members:, telling Sphinx to stop documenting inherited members once it hits class int. See autodoc docs for details.