DOC: Docstring validation ignoring directives in parameters to not report on missing period (#22423)

Author: bengineer19

pandas/tests/scripts/test_validate_docstrings.py

@@ -193,6 +193,27 @@ def contains(self, pat, case=True, na=np.nan):
  """
  pass
 
+ def mode(self, axis, numeric_only):
+ """
+ Ensure sphinx directives don't affect checks for trailing periods.
+
+ Parameters
+ ----------
+ axis : str
+ Sentence ending in period, followed by single directive.
+
+ .. versionchanged:: 0.1.2
+
+ numeric_only : boolean
+ Sentence ending in period, followed by multiple directives.
+
+ .. versionadded:: 0.1.2
+ .. deprecated:: 0.00.0
+ A multiline description,
+ which spans another line.
+ """
+ pass
+
 
 class BadGenericDocStrings(object):
  """Everything here has a bad docstring
@@ -374,6 +395,31 @@ def no_description_period(self, kind):
  Doesn't end with a dot
  """
 
+ def no_description_period_with_directive(self, kind):
+ """
+ Forgets to add a period, and also includes a directive.
+
+ Parameters
+ ----------
+ kind : str
+ Doesn't end with a dot
+
+ .. versionadded:: 0.00.0
+ """
+
+ def no_description_period_with_directives(self, kind):
+ """
+ Forgets to add a period, and also includes multiple directives.
+
+ Parameters
+ ----------
+ kind : str
+ Doesn't end with a dot
+
+ .. versionchanged:: 0.00.0
+ .. deprecated:: 0.00.0
+ """
+
  def parameter_capitalization(self, kind):
  """
  Forgets to capitalize the description.
@@ -513,7 +559,7 @@ def test_good_class(self):
 
  @pytest.mark.parametrize("func", [
  'plot', 'sample', 'random_letters', 'sample_values', 'head', 'head1',
- 'contains'])
+ 'contains', 'mode'])
  def test_good_functions(self, func):
  assert validate_one(self._import_path( # noqa: F821
  klass='GoodDocStrings', func=func)) == 0
@@ -549,6 +595,8 @@ def test_bad_generic_functions(self, func):
  'Parameter "kind: str" has no type')),
  ('BadParameters', 'no_description_period',
  ('Parameter "kind" description should finish with "."',)),
+ ('BadParameters', 'no_description_period_with_directive',
+ ('Parameter "kind" description should finish with "."',)),
  ('BadParameters', 'parameter_capitalization',
  ('Parameter "kind" description should start with a capital letter',)),
  pytest.param('BadParameters', 'blank_lines', ('No error yet?',),

scripts/validate_docstrings.py

@@ -42,6 +42,7 @@
 
 
 PRIVATE_CLASSES = ['NDFrame', 'IndexOpsMixin']
+DIRECTIVES = ['versionadded', 'versionchanged', 'deprecated']
 
 
 def _load_obj(obj_name):
@@ -234,7 +235,14 @@ def parameter_type(self, param):
  return self.doc_parameters[param][0]
 
  def parameter_desc(self, param):
- return self.doc_parameters[param][1]
+ desc = self.doc_parameters[param][1]
+ # Find and strip out any sphinx directives
+ for directive in DIRECTIVES:
+ full_directive = '.. {}'.format(directive)
+ if full_directive in desc:
+ # Only retain any description before the directive
+ desc = desc[:desc.index(full_directive)]
+ return desc
 
  @property
  def see_also(self):