feat: wrap Sphinx style long parameter descriptions (#201)

* feat: add new --style argument * test: for new --style argument * doc: for new --style argument * fix: long description before list not wrapping * Merge branch `master` * Merge branch release/v1.7.0 * fix: not finding literal blocks * chore: add pre-commit-config.yaml * chore: add pre-commit-config.yaml * refactor: change FIELD_REGEX to SPHINX_REGEX
PyCQA · May 15, 2023 · cb7bf8d · cb7bf8d
1 parent 6e06c6a
commit cb7bf8d
Show file tree

Hide file tree

Showing 12 changed files with 738 additions and 129 deletions.
diff --git a/.github/workflows/do-release.yml b/.github/workflows/do-release.yml
@@ -67,12 +67,14 @@ jobs:
           verbose: true
 
       - name: Check if diff
+        if: ${{ env.do_release == 1 }}
         continue-on-error: true
         run: >
           git diff --exit-code CHANGELOG.md &&
           (echo "### No update" && exit 1) || (echo "### Commit update")
 
       - uses: EndBug/add-and-commit@v9
+        if: ${{ env.do_release == 1 }}
         name: Commit and push if diff
         if: success()
         with:

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,57 @@
+repos:
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v4.4.0
+      hooks:
+          - id: check-docstring-first
+          - id: check-merge-conflict
+          - id: check-toml
+          - id: check-yaml
+          - id: debug-statements
+          - id: end-of-file-fixer
+          - id: no-commit-to-branch
+          - id: trailing-whitespace
+    - repo: https://github.com/psf/black
+      rev: '23.3.0'
+      hooks:
+        - id: black
+          types_or: [python, pyi]
+          language_version: python3
+    - repo: https://github.com/PyCQA/isort
+      rev: 5.12.0
+      hooks:
+        - id: isort
+          args: [--settings-file, ./pyproject.toml]
+    - repo: https://github.com/PyCQA/docformatter
+      rev: v1.6.5
+      hooks:
+        - id: docformatter
+          additional_dependencies: [tomli]
+          args: [--in-place, --config, ./pyproject.toml]
+    - repo: https://github.com/charliermarsh/ruff-pre-commit
+      rev: 'v0.0.267'
+      hooks:
+        - id: ruff
+          args: [ --select, "PL", --select, "F" ]
+    - repo: https://github.com/pycqa/pydocstyle
+      rev: 6.3.0
+      hooks:
+        - id: pydocstyle
+          additional_dependencies: [toml]
+          args: [--config, ./pyproject.toml]
+    - repo: https://github.com/pre-commit/mirrors-mypy
+      rev: v1.3.0
+      hooks:
+        - id: mypy
+          additional_dependencies: [types-python-dateutil]
+          args: [--config-file, ./pyproject.toml]
+    - repo: https://github.com/myint/eradicate
+      rev: '2.2.0'
+      hooks:
+        - id: eradicate
+          args: []
+    - repo: https://github.com/rstcheck/rstcheck
+      rev: 'v6.1.2'
+      hooks:
+        - id: rstcheck
+          additional_dependencies: [tomli]
+          args: [-r, --config, ./pyproject.toml]
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -51,3 +51,38 @@ And you invoke docformatter as follows:
       $ docformatter --config ~/.secret/path/to/pyproject.toml --wrap-summaries 68
 
 Summaries will be wrapped at 68, not 82.
+
+A Note on Options to Control Styles
+-----------------------------------
+There are various ``docformatter`` options that can be used to control the
+style of the docstring.  These options can be passed on the command line or
+set in a configuration file.  Currently, the style options are:
+
+    * ``--black``
+    * ``-s`` or ``--style``
+
+When passing the ``--black`` option, the following arguments are set
+automatically:
+
+    * ``--pre-summary-space`` is set to True
+    * ``--wrap-descriptions`` is set to 88
+    * ``--wrap-summaries`` is set to 88
+
+All of these options can be overridden from the command line.  Further, the
+``--pre-summary-space`` option only inserts a space before the summary when
+the summary begins with a double quote (").  For example:
+
+    ``"""This summary gets no space."""`` becomes ``"""This summary gets no space."""``
+
+and
+
+    ``""""This" summary does get a space."""`` becomes ``""" "This" summary does get a space."""``
+
+The ``--style`` argument takes a string which is the name of the parameter
+list style you are using.  Currently, only ``sphinx`` is recognized, but
+``epydoc``, ``numpy``, and ``google`` are future styles.  For the selected
+style, each line in the parameter lists will be wrapped at the
+``--wrap-descriptions`` length as well as any portion of the elaborate
+description preceding the parameter list.  Parameter lists that don't follow the
+passed style will cause the entire elaborate description to be ignored and
+remain unwrapped.
diff --git a/docs/source/requirements.rst b/docs/source/requirements.rst
@@ -51,17 +51,31 @@ Thus, an autoformatting tool:
     * Would be nice to produce as much output that satisfies the *methodology* requirements.
     * Would be nice to provide arguments to allow the user to turn on/off each *methodology* requirement the tool supports.
 
-Docstring Syntax
-----------------
+Docstring Style
+---------------
 
-There are at least three "flavors" of docstrings in common use today; Sphinx,
-NumPy, and Google.  Each of these docstring flavors follow the PEP 257
-*convention* requirements.  What differs between the three docstring flavors
-is the reST syntax used in the elaborate description of the multi-line
+There are at least four "flavors" of docstrings in common use today;
+Epydoc, Sphinx, NumPy, and Google.  Each of these docstring flavors follow the
+PEP 257 *convention* requirements.  What differs between the three docstring
+flavors is the reST syntax used in the parameter description of the multi-line
 docstring.
 
 For example, here is how each syntax documents function arguments.
 
+Epydoc syntax:
+
+.. code-block::
+
+    @type num_dogs: int
+    @param num_dogs: the number of dogs
+
+Sphinx syntax:
+
+.. code-block::
+
+    :param param1: The first parameter, defaults to 1.
+    :type: int
+
 Google syntax:
 
 .. code-block::
@@ -78,13 +92,6 @@ NumPy syntax:
     param1 : int
         The first parameter.
 
-Sphinx syntax:
-
-.. code-block::
-
-    :param param1: The first parameter, defaults to 1.
-    :type: int
-
 Syntax is also important to ``Docutils``.  An autoformatter should be aware of
 syntactical directives so they can be placed properly in the structure of the
 docstring.  To accommodate the various syntax flavors used in docstrings, a
@@ -201,8 +208,14 @@ the requirement falls in, the type of requirement, and whether
     ' docformatter_10.1.3.1', ' Shall maintain in-line links on one line even if the resulting line exceeds wrap length.', ' Derived', ' Shall', ' Yes [*PR #152*]'
     ' docformatter_10.1.3.2', ' Shall not place a newline between description text and a wrapped link.', ' Derived', ' Shall', ' Yes [PR #182]'
     ' docformatter_10.2', ' Should format docstrings using NumPy style.', ' Style', ' Should', ' No'
+    ' docformatter_10.2.1', ' Shall ignore docstrings in other styles when using NumPy style.', ' Shall', ' Yes'
+    ' docformatter_10.2.2', ' Shall wrap NumPy-style parameter descriptions that exceed wrap length when using NumPy style.', ' Shall', ' No'
     ' docformatter_10.3', ' Should format docstrings using Google style.', ' Style', ' Should', ' No'
-    ' docformatter_10.4', ' Should format docstrings using Sphinx style.', ' Style', ' Should', ' No'
+    ' docformatter_10.3.1', ' Shall ignore docstrings in other styles when using Google style.', ' Shall', ' Yes'
+    ' docformatter_10.3.2', ' Shall wrap Google-style parameter descriptions that exceed wrap length when using Google style.', ' Shall', ' No'
+    ' docformatter_10.4', ' Should format docstrings using Sphinx style.', ' Style', ' Should', ' Yes'
+    ' docformatter_10.4.1', ' Shall ignore docstrings in other styles when using Sphinx style.', ' Shall', ' Yes'
+    ' docformatter_10.4.2', ' Shall wrap Sphinx-style parameter descriptions that exceed wrap length when using Sphinx style.', ' Shall', ' Yes'
     ' docformatter_10.5', ' Should format docstrings compatible with black.', ' Style', ' Should', ' Yes [PR #192]'
     ' docformatter_10.5.1', ' Should wrap summaries at 88 characters by default in black mode.', ' Style', ' Should', ' Yes'
     ' docformatter_10.5.2', ' Should wrap descriptions at 88 characters by default in black mode.', ' Style', ' Should', ' Yes'
@@ -244,6 +257,9 @@ with *convention* requirements.
 ``docformatter`` currently provides these arguments for *style* requirements.
 ::
 
+    -s, --style [string, default sphinx]
+        name of the docstring syntax style to use for formatting parameter
+        lists.
     --black [boolean, default False]
         Boolean to indicate whether to format docstrings to be compatible
         with black.
@@ -306,12 +322,6 @@ The following are new arguments that are needed to implement **should** or
         Boolean to indicate whether to wrap one-line docstrings.  Provides
         option for requirement PEP_257_4.1.
 
-The following are new *style* arguments needed to accommodate the various style options:
-::
-
-    --syntax [string, default "sphinx"]
-        One of sphinx, numpy, or google
-
 Issue and Version Management
 ----------------------------
 

diff --git a/docs/source/usage.rst b/docs/source/usage.rst
@@ -43,6 +43,12 @@ help output provides a summary of these options:
       -n, --non-cap         list of words not to capitalize when they appear as the
                             first word in the summary
 
+      -s style, --style style
+                            the docstring style to use when formatting parameter
+                            lists (default: sphinx)
+      --black
+                            make formatting compatible with standard black options
+                            (default: False)
       --wrap-summaries length
                             wrap long summary lines at this length; set
                             to 0 to disable wrapping
@@ -51,11 +57,12 @@ help output provides a summary of these options:
                             wrap descriptions at this length; set to 0 to
                             disable wrapping
                             (default: 72)
-      --black
-                            make formatting consistent with black, setting
-                            wrap-summaries and wrap-descriptions to a default 88
-                            if not otherwise specified
-                            (default: False)
+      --force-wrap
+                            force descriptions to be wrapped even if it may result
+                            in a mess (default: False)
+      --tab_width width
+                            tabs in indentation are this many characters when
+                            wrapping lines (default: 1)
       --blank
                             add blank line after elaborate description
                             (default: False)
@@ -75,21 +82,14 @@ help output provides a summary of these options:
                             place closing triple quotes on a new-line when a
                             one-line docstring wraps to two or more lines
                             (default: False)
-      --force-wrap
-                            force descriptions to be wrapped even if it may result
-                            in a mess (default: False)
-      --tab_width width
-                            tabs in indentation are this many characters when
-                            wrapping lines (default: 1)
       --range start_line end_line
                             apply docformatter to docstrings between these lines;
                             line numbers are indexed at 1
       --docstring-length min_length max_length
                             apply docformatter to docstrings of given length range
       --non-strict
                             do not strictly follow reST syntax to identify lists
-                            (see issue #67)
-                            (default: False)
+                            (see issue #67) (default: False)
       --config CONFIG
                             path to file containing docformatter options
                             (default: ./pyproject.toml)

diff --git a/src/docformatter/__main__.py b/src/docformatter/__main__.py
@@ -71,6 +71,9 @@ def _help():
                         list of words not to capitalize when they appear as the
                         first word in the summary
 
+  -s style, --style style
+                        the docstring style to use when formatting parameter
+                        lists (default: sphinx)
   --black               make formatting compatible with standard black options
                         (default: False)
   --wrap-summaries length

diff --git a/src/docformatter/configuration.py b/src/docformatter/configuration.py
@@ -158,6 +158,13 @@ def do_parse_arguments(self) -> None:
             _default_wrap_descriptions = 72
             _default_pre_summary_space = "false"
 
+        self.parser.add_argument(
+            "-s",
+            "--style",
+            default=self.flargs_dct.get("style", "sphinx"),
+            help="name of the docstring style to use when formatting "
+                 "parameter lists (default: sphinx)",
+        )
         self.parser.add_argument(
             "--wrap-summaries",
             default=int(

diff --git a/src/docformatter/format.py b/src/docformatter/format.py
@@ -489,6 +489,7 @@ def _do_format_docstring(
             _syntax.is_some_sort_of_list(
                 summary,
                 self.args.non_strict,
+                self.args.style,
             )
             or _syntax.do_find_directives(summary)
         ):
@@ -613,6 +614,7 @@ def _do_format_multiline_docstring(
             wrap_length=self.args.wrap_descriptions,
             force_wrap=self.args.force_wrap,
             strict=self.args.non_strict,
+            style=self.args.style,
         )
         post_description = "\n" if self.args.post_description_blank else ""
         return f'''\