feat: integrate flake8-docstring

most of the rules are disabled since it will take longer to fix them all

maybe in future version we can fix them one by one

news/add-flake8-docstrings.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* add flake8-docstrings to the project. it integrates pydocstyle to flake8.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

requirements/tests.txt

@@ -1,6 +1,7 @@
 py
 pytest>=5.4
 flake8
+flake8-docstrings
 pytest-cov
 pytest-timeout
 prompt-toolkit>=2.0

setup.cfg

@@ -23,6 +23,28 @@ exclude =
     pygments_cache.py
 # lint nits that are acceptable in Xonsh project:
 ignore =
+    D100, # Missing docstring in public module
+    D101, # Missing docstring in public class
+    D102, # Missing docstring in public method
+    D103, # Missing docstring in public function
+    D104, # Missing docstring in public package
+    D105, # Missing docstring in magic method
+    D200, # One-line docstring should fit on one line with quotes
+    D202, # No blank lines allowed after function docstring
+    D205, # 1 blank line required between summary line and description
+    D207, # Docstring is under-indented
+    D208, # Docstring is over-indented
+    D209, # Multi-line docstring closing quotes should be on a separate line
+    D210, # No whitespaces allowed surrounding docstring text
+    D301, # Use r""" if any backslashes in a docstring
+    D400, # First line should end with a period
+    D401, # First line should be in imperative mood
+    D403, # First word of the first line should be properly capitalized
+    D404, # First word of the docstring should not be `This`
+    D406, # Section name should end with a newline
+    D409, # Section underline should match the length of its name
+    D411, # Missing blank line before section
+    D407, # Missing dashed underline after section
     E122,
     # E203 whitespace before ':'
     E203,
@@ -72,3 +94,6 @@ per-file-ignores =
     xonsh/tools.py:E305,
     xonsh/winutils.py:E305,
     xonsh/xoreutils/*.py:E722 E305,
+
+# pydocstyle plugin
+docstring-convention=numpy

xonsh/aliases.py

@@ -724,7 +724,8 @@ def showcmd(args, stdin=None):
     optional arguments:
       -h, --help            show this help message and exit
 
-    example:
+    Example:
+    -------
       >>> showcmd echo $USER can't hear "the sea"
       ['echo', 'I', "can't", 'hear', 'the sea']
     """

xonsh/environ.py

@@ -400,7 +400,7 @@ class LsColors(cabc.MutableMapping):
                 p.pretty(dict(self))
 
     def is_target(self, key) -> bool:
-        "Return True if key is 'target'"
+        """Return True if key is 'target'"""
         return key in self._targets
 
     def detype(self):

xonsh/lexer.py

@@ -333,7 +333,6 @@ def handle_token(state, token):
 
     Parameters
     ----------
-
     state :
         The current state of the lexer, including information about whether
         we are in Python mode or subprocess mode, which changes the lexer's

xonsh/parsers/base.py

@@ -3355,7 +3355,7 @@ class BaseParser(object):
         p[0] = p2
 
     def p_empty(self, p):
-        "empty : "
+        """empty : """
         p[0] = None
 
     def p_error(self, p):

xonsh/ptk_shell/updator.py

@@ -75,7 +75,6 @@ class AsyncPrompt:
 
         Parameters
         -----------
-
         on_complete:
             callback to notify after all the futures are completed
         """

xonsh/tools.py

@@ -77,6 +77,7 @@ class XonshCalledProcessError(XonshError, subprocess.CalledProcessError):
     returncode of the command is nonzero.
 
     Example:
+    -------
         try:
             for line in !(ls):
                 print(line)
@@ -1254,7 +1255,7 @@ _FALSES = LazyObject(
 
 
 def to_bool(x):
-    """"Converts to a boolean in a semantically meaningful way."""
+    """Converts to a boolean in a semantically meaningful way."""
     if isinstance(x, bool):
         return x
     elif isinstance(x, str):
@@ -1264,7 +1265,7 @@ def to_bool(x):
 
 
 def to_bool_or_none(x):
-    """"Converts to a boolean or none in a semantically meaningful way."""
+    """Converts to a boolean or none in a semantically meaningful way."""
     if x is None or isinstance(x, bool):
         return x
     elif isinstance(x, str):