release: v1.7.2 (#220)

* fix: excessive whitespace in middle of line * test: fix failing tests * fix: space after field with no description * fix: wrapping reST section admonitions * doc: documentation for new argument * fix: not wrapping fields at proper wrap length * test: fix failing tests * fix: not considering field name in wrap length * fix: adding space in :meth: role with no link * fix: sphinx style wrapping fields with parentheses * fix: no summary description treated like summary * docs: update documentation * fix: adding blank space when no field body * chore: update version string for release --------- Signed-off-by: Doyle Rowland <doyle.rowland@reliaqual.com>
PyCQA · Jun 7, 2023 · 4f8b39a · 4f8b39a
1 parent bd0b702
commit 4f8b39a
Show file tree

Hide file tree

Showing 15 changed files with 685 additions and 302 deletions.
diff --git a/.github/workflows/do-prioritize-issues.yml b/.github/workflows/do-prioritize-issues.yml
@@ -24,22 +24,19 @@ jobs:
         uses: weibullguy/get-labels-action@main
 
       - name: Add High Urgency Labels
-        if: |
-          ${{ (contains(steps.getlabels.outputs.labels, "C: convention") && contains (steps.getlabels.outputs.labels, "P: bug")) }}
+        if: '${{ (contains(steps.getlabels.outputs.labels, "C: convention") && contains (steps.getlabels.outputs.labels, "P: bug")) }}'
         uses: andymckay/labeler@master
         with:
           add-labels: "U: high"
 
       - name: Add Medium Urgency Labels
-        if: |
-          ${{ (contains(steps.getlabels.outputs.labels, "C: style") && contains(steps.getlabels.outputs.labels, "P: bug")) || (contains(steps.getlabels.outputs.labels, "C: stakeholder") && contains(steps.getlabels.outputs.labels, "P: bug")) || (contains(steps.getlabels.outputs.labels, "C: convention") && contains(steps.getlabels.outputs.labels, "P: enhancement")) }}
+        if: '${{ (contains(steps.getlabels.outputs.labels, "C: style") && contains(steps.getlabels.outputs.labels, "P: bug")) || (contains(steps.getlabels.outputs.labels, "C: stakeholder") && contains(steps.getlabels.outputs.labels, "P: bug")) || (contains(steps.getlabels.outputs.labels, "C: convention") && contains(steps.getlabels.outputs.labels, "P: enhancement")) }}'
         uses: andymckay/labeler@master
         with:
           add-labels: "U: medium"
 
       - name: Add Low Urgency Labels
-        if: |
-          ${{ (contains(steps.getlabels.outputs.labels, "C: style") && contains(steps.getlabels.outputs.labels, "P: enhancement")) || (contains(steps.getlabels.outputs.labels, "C: stakeholder") && contains(steps.getlabels.outputs.labels, "P: enhancement")) || contains(steps.getlabels.outputs.labels, "doc") || contains(steps.getlabels.outputs.labels, "chore") }}
+        if: '${{ (contains(steps.getlabels.outputs.labels, "C: style") && contains(steps.getlabels.outputs.labels, "P: enhancement")) || (contains(steps.getlabels.outputs.labels, "C: stakeholder") && contains(steps.getlabels.outputs.labels, "P: enhancement")) || contains(steps.getlabels.outputs.labels, "doc") || contains(steps.getlabels.outputs.labels, "chore") }}'
         uses: andymckay/labeler@master
         with:
           add-labels: "U: low"
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,15 +1,17 @@
+# type: ignore
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+"""Configuration file for the Sphinx documentation builder."""
 
 project = "docformatter"
 copyright = "2022-2023, Steven Myint"
 author = "Steven Myint"
-release = "1.7.1"
+release = "1.7.2"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -68,20 +68,51 @@ automatically:
     * ``--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:
+All of these options can be overridden from the command line or in the configuration
+file.  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`` and ``epytext`` are recognized,
-but ``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.
+The ``--style`` argument takes a string which is the name of the field list style you
+are using.  Currently, only ``sphinx`` and ``epytext`` are recognized, but ``numpy``
+and ``google`` are future styles.  For the selected style, each line in the field lists
+will be wrapped at the ``--wrap-descriptions`` length as well as any portion of the
+elaborate description preceding the parameter list.  Field lists that don't follow the
+passed style will cause the entire elaborate description to be ignored and remain
+unwrapped.
+
+A Note on reST Header Adornments Regex
+--------------------------------------
+``docformatter-1.7.2`` added a new option ``--rest-section-adorns``.  This allows for
+setting the characters used as overline and underline adornments for reST section
+headers.  Per the `ReStructuredText Markup Specification <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections>`_,
+the following are all valid adornment characters,
+
+.. code-block::
+
+    ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
+
+Thus, the default regular expression ``[!\"#$%&'()*+,-./:;<=>?@[\]^_`{|}~]{4,}``
+looks for any of these characters appearing at least four times in a row.  Note that the
+list of valid adornment characters includes the double quote (") and the greater-than
+sign (>).  Four repetitions was selected because:
+
+    * Docstrings open and close with triple double quotes.
+    * Doctests begin with >>>.
+    * It would be rare for a section header to consist of fewer than four characters.
+
+The user can override this default list of characters by passing a regex from the
+command line or setting the ``rest-section-adorns`` option in the configuration file.
+It may be usefule to set this regex to only include the subset of characters you
+actually use in your docstrings.  For example, to only recognize the recommended list
+in the ReStructuredText Markup Specification, the following regular expression would
+be used:
+
+.. code-block::
+
+    [=-`:.'"~^_*+#]{4,}
diff --git a/docs/source/requirements.rst b/docs/source/requirements.rst
@@ -57,8 +57,7 @@ Docstring Style
 There are at least four "flavors" of docstrings in common use today;
 Epytext, 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.
+flavors is the reST syntax used in the field list of the multi-line docstring.
 
 For example, here is how each syntax documents function arguments.
 
@@ -97,11 +96,10 @@ syntactical directives so they can be placed properly in the structure of the
 docstring.  To accommodate the various syntax flavors used in docstrings, a
 third requirement category is introduced, *style*.
 
-Another consideration in for the *style* category is line wrapping.
-According to PEP 257, splitting a one-line docstring is to allow "Emacs’
-``fill-paragraph`` command" to be used.  The ``fill-paragraph`` command is a
-line-wrapping command.  Additionally, it would be desirable to wrap
-docstrings for visual continuity with the code.
+Another consideration in the *style* category is line wrapping.  According to PEP
+257, splitting a one-line docstring is to allow "Emacs’ ``fill-paragraph`` command"
+to be used.  The ``fill-paragraph`` command is a line-wrapping command.  Additionally,
+it would be desirable to wrap docstrings for visual continuity with the code.
 
 NumPy makes a stylistic decision to place a blank line after the long
 description.
@@ -141,7 +139,7 @@ The following items are exceptions or interpretations of the PEP 257
 requirements:
 
     * One-line and summary lines can end with any punctuation.  ``docformatter`` will recognize any of [. ! ?].  Exception to requirement PEP_257_4.5; consistent with Google style.  See also #56 for situations when this is not desired.
-    * One-line and summary lines will have the first word capitalized.  ``docformatter`` will capitalize the first word for grammatical correctness.  Interpretation of requirement PEP_257_4.5.
+    * One-line and summary lines will have the first word capitalized.  ``docformatter`` will capitalize the first word for grammatical correctness.  Interpretation of requirement PEP_257_4.5.  Some proper nouns are explicitly spelled using a lowercase letter (e.g., ``docformatter``).  A user option is provided for a list of words to maintain lower case.
     * PEP 257 discusses placing closing quotes on a new line in the multi-line section.  However, it really makes no sense here as there is no way this condition could be met for a multi-line docstring.  Given the basis provided in PEP 257, this requirement really applies to wrapped one-liners.  Thus, this is assumed to apply to wrapped one-liners and the closing quotes will be placed on a line by themselves in this case.  However, an argument will be provided to allow the user to select their desired behavior.  Interpretation of requirement PEP_257_5.5.
 
 These give rise to the *derived* requirement category which would also cover
@@ -208,22 +206,28 @@ 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.1', ' Shall ignore docstrings in other styles when using NumPy style.', ' 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.3.1', ' Shall ignore docstrings in other styles when using Google style.', ' Shall', ' Yes'
+    ' docformatter_10.3.1', ' Shall ignore docstrings in other styles when using Google style.', ' 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.1', ' Shall ignore docstrings in other styles when using Sphinx style.', ' 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.4.3', ' Shall ensure one blank space between a field name and field body.', ' Style', ' Shall', ' Yes [PR #220]'
+    ' docformatter_10.4.3.1', ' Shall NOT add a blank space after a field name when the field body is a link.', ' Style', ' Shall', ' Yes [PR #220]'
+    ' docformatter_10.4.3.2', ' Shall NOT add a blank space after a field name when there is no field body.', ' Style', ' Shall', ' Yes [PR #220]'
     ' 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'
     ' docformatter_10.5.3', ' Should insert a space before the first word in the summary if that word is quoted when in black mode.', ' Style', ' Should', ' Yes'
     ' docformatter_10.5.4', ' Default black mode options should be over-rideable by passing arguments or using configuration files.', ' Style', ' Should', ' Yes'
     ' docformatter_10.6', ' Should format docstrings using Epytext style.', ' Style', ' Should', ' Yes'
-    ' docformatter_10.6.1', ' Shall ignore docstrings in other styles when using Epytext style.', ' Shall', ' Yes'
+    ' docformatter_10.6.1', ' Shall ignore docstrings in other styles when using Epytext style.', ' Style', ' Shall', ' Yes'
     ' docformatter_10.6.2', ' Shall wrap Epytext-style parameter descriptions that exceed wrap length when using Epytext style.', ' Shall', ' Yes'
+    ' docformatter_10.7', ' Should format docstrings using ReStructured Text (reST) directives.', ' Style', ' Should', ' No'
+    ' docformatter_10.7.1', ' Shall NOT wrap section headers or their adornments.', ' Style', 'Shall', ' Yes [PR #220]'
+    ' docformatter_10.7.2', ' Shall NOT wrap literal blocks.', ' Style', ' Shall', ' Yes [PR #211]'
     ' docformatter_11', '**Program Control**'
     ' docformatter_11.1', ' Should check formatting and report incorrectly documented docstrings.', ' Stakeholder', ' Should', ' Yes [*PR #32*]'
     ' docformatter_11.2', ' Should fix formatting and save changes to file.', ' Stakeholder', ' Should', ' Yes'
@@ -263,6 +267,11 @@ with *convention* requirements.
     -s, --style [string, default sphinx]
         name of the docstring syntax style to use for formatting parameter
         lists.
+    --rest-section-adorns [REGEX, default [!\"#$%&'()*+,-./\\:;<=>?@[]^_`{|}~]{4,}]
+        regular expression for identifying reST section adornments
+    -n, --non-cap [string, default []]
+        list of words not to capitalize when they appear as the first word in the
+        summary
     --black [boolean, default False]
         Boolean to indicate whether to format docstrings to be compatible
         with black.

diff --git a/docs/source/usage.rst b/docs/source/usage.rst
@@ -21,13 +21,15 @@ help output provides a summary of these options:
 
 .. code-block:: console
 
-    usage: docformatter [-h] [-i | -c] [-r] [--wrap-summaries length]
-                        [--wrap-descriptions length] [--black] [--blank]
-                        [--pre-summary-newline] [--make-summary-multi-line]
-                        [--force-wrap] [--range start_line end_line]
-                        [--docstring-length min_length max_length]
-                        [--config CONFIG] [--version]
-                        files [files ...]
+    usage: docformatter [-h] [-i | -c] [-d] [-r] [-e [EXCLUDE ...]]
+                        [-n [NON-CAP ...]] [-s [style]] [--rest-section-adorns REGEX]
+                        [--black] [--wrap-summaries length]
+                        [--wrap-descriptions length] [--force-wrap]
+                        [--tab-width width] [--blank] [--pre-summary-newline]
+                        [--pre-summary-space] [--make-summary-multi-line]
+                        [--close-quotes-on-newline] [--range line line]
+                        [--docstring-length length length] [--non-strict]
+                        [--config CONFIG] [--version] files [files ...]
 
     Formats docstrings to follow PEP 257.
 
@@ -46,17 +48,17 @@ help output provides a summary of these options:
       -s style, --style style
                             the docstring style to use when formatting parameter
                             lists.  One of epytext, sphinx. (default: sphinx)
-      --black
-                            make formatting compatible with standard black options
+      --rest-section-adorns REGEX
+                            regular expression for identifying reST section adornments
+                            (default: [!\"#$%&'()*+,-./\\:;<=>?@[]^_`{|}~]{4,})
+      --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
-                            (default: 79)
+                            wrap long summary lines at this length; set to 0 to
+                            disable wrapping (default: 79, 88 with --black option)
       --wrap-descriptions length
-                            wrap descriptions at this length; set to 0 to
-                            disable wrapping
-                            (default: 72)
+                            wrap descriptions at this length; set to 0 to disable
+                            wrapping (default: 72, 88 with --black option)
       --force-wrap
                             force descriptions to be wrapped even if it may result
                             in a mess (default: False)

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "docformatter"
-version = "1.7.1"
+version = "1.7.2"
 description = "Formats docstrings to follow PEP 257"
 authors = ["Steven Myint"]
 maintainers = [
@@ -95,6 +95,9 @@ disable = [
 [tool.docformatter]
 black = true
 non-strict = false
+non-cap = [
+	"docformatter",
+]
 
 [tool.pydocstyle]
 convention = "pep257"

diff --git a/src/docformatter/__main__.py b/src/docformatter/__main__.py
@@ -41,7 +41,8 @@ def _help():
     print(
         """\
 usage: docformatter [-h] [-i | -c] [-d] [-r] [-e [EXCLUDE ...]]
-                    [-n [NON-CAP ...]] [--black] [--wrap-summaries length]
+                    [-n [NON-CAP ...]] [-s [style]] [--rest-section-adorns REGEX]
+                    [--black] [--wrap-summaries length]
                     [--wrap-descriptions length] [--force-wrap]
                     [--tab-width width] [--blank] [--pre-summary-newline]
                     [--pre-summary-space] [--make-summary-multi-line]
@@ -69,6 +70,9 @@ def _help():
   -s style, --style style
                         the docstring style to use when formatting parameter
                         lists.  One of epytext, sphinx. (default: sphinx)
+  --rest-section-adorns REGEX
+                        regular expression for identifying reST section adornments
+                        (default: [!\"#$%&'()*+,-./\\:;<=>?@[]^_`{|}~]{4,})
   --black               make formatting compatible with standard black options
                         (default: False)
   --wrap-summaries length
@@ -113,7 +117,7 @@ def _main(argv, standard_out, standard_error, standard_in):
 
     if "--help" in configurator.args_lst:
         _help()
-        sys.exit()
+        return 0
     else:
         configurator.do_parse_arguments()
 

diff --git a/src/docformatter/__pkginfo__.py b/src/docformatter/__pkginfo__.py
@@ -23,4 +23,4 @@
 # SOFTWARE.
 """Package information for docformatter."""
 
-__version__ = "1.7.1"
+__version__ = "1.7.2"
diff --git a/src/docformatter/configuration.py b/src/docformatter/configuration.py
@@ -139,9 +139,8 @@ def do_parse_arguments(self) -> None:
             action="store",
             nargs="*",
             default=self.flargs_dct.get("non-cap", None),
-            help="list of words not to capitalize "
-            "when they appear as the "
-            "first word in the summary",
+            help="list of words not to capitalize when they appear as the first word "
+            "in the summary",
         )
         self.parser.add_argument(
             "--black",
@@ -171,6 +170,15 @@ def do_parse_arguments(self) -> None:
             help="name of the docstring style to use when formatting "
             "parameter lists (default: sphinx)",
         )
+        self.parser.add_argument(
+            "--rest-section-adorns",
+            type=str,
+            dest="rest_section_adorns",
+            default=self.flargs_dct.get(
+                "rest_section_adorns", r"[!\"#$%&'()*+,-./:;<=>?@[\]^_`{|}~]{4,}"
+            ),
+            help="regex for identifying reST section header adornments",
+        )
         self.parser.add_argument(
             "--wrap-summaries",
             default=int(self.flargs_dct.get("wrap-summaries", _default_wrap_summaries)),
@@ -229,7 +237,7 @@ def do_parse_arguments(self) -> None:
                 "pre-summary-space", _default_pre_summary_space
             ).lower()
             == "true",
-            help="add a space after the opening triple quotes " "(default: False)",
+            help="add a space after the opening triple quotes (default: False)",
         )
         self.parser.add_argument(
             "--make-summary-multi-line",