CI: add pydocstyle to code_checks

ci/code_checks.sh

@@ -316,6 +316,13 @@ fi
 ### DOCSTRINGS ###
 if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
 
+    echo "pydocstyle --version"
+    pydocstyle --version
+
+    MSG='Validate docstrings using pydocstyle (see setup.cfg for selected error codes)' ; echo $MSG
+    pydocstyle pandas
+    RET=$(($RET + $?)) ; echo $MSG "DONE"
+
     MSG='Validate docstrings (GL03, GL04, GL05, GL06, GL07, GL09, GL10, SS04, SS05, PR03, PR04, PR05, PR10, EX04, RT01, RT04, RT05, SA02, SA03, SA05)' ; echo $MSG
     $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=GL03,GL04,GL05,GL06,GL07,GL09,GL10,SS04,SS05,PR03,PR04,PR05,PR10,EX04,RT01,RT04,RT05,SA02,SA03,SA05
     RET=$(($RET + $?)) ; echo $MSG "DONE"

environment.yml

@@ -23,6 +23,7 @@ dependencies:
   - isort  # check that imports are in the right order
   - mypy=0.730
   - pycodestyle  # used by flake8
+  - pydocstyle
 
   # documentation
   - gitpython  # obtain contributors from git for whatsnew

pandas/core/arrays/datetimes.py

@@ -559,7 +559,6 @@ def __iter__(self):
         ------
         tstamp : Timestamp
         """
-
         # convert in chunks of 10k for efficiency
         data = self.asi8
         length = len(self)
@@ -820,7 +819,9 @@ def tz_convert(self, tz):
         dtype = tz_to_dtype(tz)
         return self._simple_new(self.asi8, dtype=dtype, freq=self.freq)
 
-    def tz_localize(self, tz, ambiguous="raise", nonexistent="raise"):
+    # TODO: remove # noqa once https://github.com/PyCQA/pydocstyle/pull/441
+    # is merged
+    def tz_localize(self, tz, ambiguous="raise", nonexistent="raise"):  # noqa
         """
         Localize tz-naive Datetime Array/Index to tz-aware
         Datetime Array/Index.
@@ -1640,7 +1641,6 @@ def to_julian_date(self):
         0 Julian date is noon January 1, 4713 BC.
         https://en.wikipedia.org/wiki/Julian_day
         """
-
         # http://mysite.verizon.net/aesir_research/date/jdalg2.htm
         year = np.asarray(self.year)
         month = np.asarray(self.month)
@@ -1705,7 +1705,6 @@ def sequence_to_dt64ns(
     ------
     TypeError : PeriodDType data is passed
     """
-
     inferred_freq = None
 
     dtype = _validate_dt64_dtype(dtype)

pandas/core/tools/datetimes.py

@@ -538,7 +538,7 @@ def to_datetime(
     infer_datetime_format=False,
     origin="unix",
     cache=True,
-):
+):  # noqa: D207
     """
     Convert argument to datetime.
 

pandas/io/excel/_openpyxl.py

@@ -393,6 +393,7 @@ def _convert_to_protection(cls, protection_dict):
 
         Returns
         -------
+        openpyxl.styles.Protection
         """
         from openpyxl.styles import Protection
 

requirements-dev.txt

@@ -14,6 +14,7 @@ flake8-rst>=0.6.0,<=0.7.0
 isort
 mypy==0.730
 pycodestyle
+pydocstyle
 gitpython
 gitdb2==2.0.6
 sphinx

setup.cfg

@@ -49,6 +49,20 @@ ignore = E402,  # module level import not at top of file
 exclude =
     doc/source/development/contributing_docstring.rst
 
+[pydocstyle]
+select = D201, # No blank lines allowed before function docstring
+         D202, # No blank lines allowed after function docstring
+         D204, # 1 blank line required after class docstring
+         D207, # Docstring is under-indented
+         D208, # Docstring is over-indented
+         D209, # Multi-line docstring closing quotes should be on a separate line
+         D213, # Multi-line docstring summary should start at the second line
+         D300, # Use triple double quotes
+         D409, # Section underline should match the length of its name
+         D411, # Missing blank line before section
+         D412, # No blank lines allowed between a section header and its content
+         D414, # Section has no content
+
 [tool:pytest]
 # sync minversion with setup.cfg & install.rst
 minversion = 4.0.2