-
Notifications
You must be signed in to change notification settings - Fork 86
Closed
Labels
C: styleRelates to docstring format style (e.g., Google, NumPy, Sphinx)Relates to docstring format style (e.g., Google, NumPy, Sphinx)P: bugPEP 257 violation or existing functionality that doesn't work as documentedPEP 257 violation or existing functionality that doesn't work as documented
Description
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 = 88A screenshot to help visualize the desired result:
Metadata
Metadata
Assignees
Labels
C: styleRelates to docstring format style (e.g., Google, NumPy, Sphinx)Relates to docstring format style (e.g., Google, NumPy, Sphinx)P: bugPEP 257 violation or existing functionality that doesn't work as documentedPEP 257 violation or existing functionality that doesn't work as documented
