PyCQA / docformatter

Formats docstrings to follow PEP 257
https://pypi.python.org/pypi/docformatter
MIT License
530 stars 61 forks source link

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

Closed electric-coder closed 1 year ago

electric-coder commented 1 year ago

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

weibullguy commented 1 year ago

v1.7.2-rc4 fixes this.

weibullguy commented 1 year ago

Closing this issue to #231.