Skip to content

Elaborate description with Sphinx cross-references is converted to field list. #227

@electric-coder

Description

@electric-coder

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:

  1. Remove the text preceding the first cross-reference (possibly aiming to convert the :class: roles into a field list).
  2. 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:

docformatter1

Metadata

Metadata

Assignees

No one assigned

    Labels

    C: styleRelates to docstring format style (e.g., Google, NumPy, Sphinx)P: bugPEP 257 violation or existing functionality that doesn't work as documented

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions