Elaborate description with Sphinx cross-references is converted to field list.
electric-coder opened this issue · 2 comments
The following example is of a PEP 257 multi-line docstring with a summary line and an "elaborate description" paragraph that contains Sphinx cross-references in the "elaborate description".
The docstring does not contain any docstring sections and (thus) no reST field list. This is because the class implements a series of abstract classes from collections.abc
and doesn't have any attributes of its own.
class A:
pass
class B:
"""Let's write a cross-reference to the above :class:`A`.
Implements the following abstract class text text text text text text
more text :class:`collections.abc.Set` text text text text text text
:class:`frozenset` trailing text text text text text text text text
:class:`collections.abc.Hashable` text text text text text text text text.
"""
When running docformatter 1.7.1 on the example it offers to:
- Remove the text preceding the first cross-reference (possibly aiming to convert the
:class:
roles into a field list). - Introduce a space between the role and the opening backtick, turning
:class:`title <link>`
into:class: `title <link>`
. (This change would break the cross-references).
@@ -9,10 +9,10 @@
class B:
"""Let's write a cross-reference to the above :class:`A`.
- Implements the following abstract class text text text text text text
- more text :class:`collections.abc.Set` text text text text text text
- :class:`frozenset` trailing text text text text text text text text
- :class:`collections.abc.Hashable` text text text text text text text text.
+ Implements the following abstract class text text text text text text more text
+ :class: `collections.abc.Set` text text text text text text
+ :class: `frozenset` trailing text text text text text text text text
+ :class: `collections.abc.Hashable` text text text text text text text text.
"""
Notice that if the docstring did have a docstring section docformatter would format it correctly, the following example works as expected:
class A:
pass
class B:
"""Let's write a cross-reference to the above :class:`A`.
Implements the following abstract class text text text text text text
more text :class:`collections.abc.Set` text text text text text text
:class:`frozenset` trailing text text text text text text text text
:class:`collections.abc.Hashable` text text text text text text text text.
Args:
an_arg (str): Explains the arg.
"""
Using docformatter 1.7.1 with the following settings in pyproject.toml
:
[tool.docformatter]
black = true
wrap-descriptions = 88
wrap-summaries = 88
A screenshot to help visualize the desired result:
v1.7.2-rc4 fixes this.
Closing this issue to #231.