Repository navigation
Accommodate Sphinx option by changing docstring return type of "integer" to "int". #100989
Description
Bug report
When collections.deque is subclassed and the resulting class is documented with Sphinx using the option :inherited-members:, the following error appears:
WARNING: py:class reference target not found: integer -- return number of occurrences of value
I assume this is because the PyDoc_STRVAR docstring of the C-implementation is not compliant to PEP-7 as required in PyDoc_STRVAR:
cpython/Modules/_collectionsmodule.c
Lines 992 to 993 in d9dff4c
And everything after -> is interpreted as type hint.
This can be reproduced with e.g. a python module sub_deque.py:
class SubDeque(deque):
pass
and a documenation file docs/src/sub_deque.rst:
.. automodule:: sub_deque
:inherited-members:
which is then built with Sphinx: sphinx-build -W docs/src docs/dist.
I'd be happy to provide a patch for this myself if you feel this issue should be fixed.
Your environment
- CPython versions tested on: 3.7 - 3.11
- Operating system and architecture: Arch Linux & Ubuntu
Linked PRs
- gh-100989: Fix docstrings of
collections.deque#100990 - [3.11] gh-100989: Improve the accuracy of collections.deque docstrings (GH-100990) #102910
- [3.10] gh-100989: Improve the accuracy of collections.deque docstrings (GH-100990) #102911
- gh-100989: Revert #100990: Improve the accuracy of collections.deque docstrings #102949
- GH-100989: Revert Improve the accuracy of collections.deque docstrings #102979
- [3.11] GH-100989: Revert Improve the accuracy of collections.deque docstrings (GH-102979) #102984
- [3.10] GH-100989: Revert Improve the accuracy of collections.deque docstrings (GH-102979) #102985
- GH-100989: remove annotation from docstring #102991
- [3.11] GH-100989: remove annotation from docstring (GH-102991) #102992
Activity
pythonGH-100989: Fix docstrings of collections.deque
pythongh-100989: Fix docstrings of collections.deque
rhettinger commentedon Jan 12, 2023
You can change "integer" to "int" if you like. The other changes look gratuitous.
Also, PEP 7 predates modern type annotations. Doc strings are allowed to put any text as the return type as long as it is interpretable by a human. It is unfortunate that Sphinx is assuming otherwise. How would it handle user defined types or types defined in type comments?
[-]Docstrings of `collections.deque` not compliant to PEP-7[/-][+]Accommodate Sphinx option by changing docstring return type of "integer" to "int".[/+]timobrembeck commentedon Jan 12, 2023
Ok, thanks for your feedback!
Still, changing it to
D.count(value) -> int -- return number of occurrences of valuewould just cause Sphinx to literally search for the typeint -- return number of occurrences of valuewhich it wouldn't find either. Are you fine with including the new line after the return type? SoD.count(value) -> int\n ...? Most of the other modules seem to follow that convention:cpython/Modules/atexitmodule.c
Line 211 in 0ace820
cpython/Modules/_threadmodule.c
Line 190 in 762745a
cpython/Modules/nismodule.c
Line 28 in 81f7359
Although to be fair, I also found quite a few other modules which use an inconsistent format, e.g.
cpython/Modules/timemodule.c
Line 160 in 3e06b50
which I would change to
time() -> floatto match the correct type and allow the cross-referencing between documentations.Are there better options to annotate types in C modules? If so, I think it should be mentioned in the docs of
PyDoc_STRVAR...User defined types are usually documented in the project that Sphinx is invoked in, and thus it'll find the reference to the custom type.
pythongh-100989: Fix docstrings of collections.deque
pythongh-100989: Fix docstrings of collections.deque
timobrembeck commentedon Feb 16, 2023
@rhettinger Do you have any more thoughts on this? Anything specific you want me to change in the PR?
pythongh-100989: Fix docstrings of collections.deque
pythongh-100989: Fix docstrings of collections.deque
pythongh-100989: Fix docstrings of collections.deque
gh-100989: Improve the accuracy of collections.deque docstrings (#100990
pythongh-100989: Improve the accuracy of collections.deque docstrings (…
27 remaining items
GH-100989: Revert Improve the accuracy of collections.deque docstrings (
GH-100989: Revert Improve the accuracy of collections.deque docstrings (
timobrembeck commentedon Mar 24, 2023
@rhettinger Yes, Sphinx uses this regex to determine whether a docstring line is a signature, and without the
->, the following text is not matched as return type. Thus, the whole line would be correctly identified as normal text.I could however also open a ticket on Sphinx' side to ignore everything after
--. I mean this isn't documented anywhere, but as you said, the tools should follow cpython's conventions and not vice versa, and since this pattern is used in the code base for quite some time now, it could be considered a convention.Thanks a lot for revisiting this issue!
pythonGH-100989: remove annotation from docstring
GH-100989: remove annotation from docstring (GH-102991)
pythonGH-100989: remove annotation from docstring (pythonGH-102991)
rhettinger commentedon Mar 24, 2023
Thanks for the report.
GH-100989: remove annotation from docstring (GH-102991)
pythongh-100989: Improve the accuracy of collections.deque docstrings (…
pythonGH-100989: Revert Improve the accuracy of collections.deque doc…
pythonGH-100989: remove annotation from docstring (pythonGH-102991)
pythongh-100989: Improve the accuracy of collections.deque docstrings (…
pythonGH-100989: Revert Improve the accuracy of collections.deque doc…
pythonGH-100989: remove annotation from docstring (pythonGH-102991)