From dfc522fe9c1289842890aba95611e55653d08feb Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 2 Mar 2018 10:46:48 +0100 Subject: [PATCH 1/5] Don't print error if there are no parameters --- scripts/validate_docstrings.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 7807785c24751..3dc2fb838ad1b 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -149,7 +149,8 @@ def parameter_mismatches(self): extra = set(doc_params) - set(signature_params) if extra: errs.append('Unknown parameters {!r}'.format(extra)) - if not missing and not extra and signature_params != doc_params: + if (not missing and not extra and signature_params != doc_params + and not (not signature_params and not doc_params)): errs.append('Wrong parameters order. ' + 'Actual: {!r}. '.format(signature_params) + 'Documented: {!r}'.format(doc_params)) From 5020d8feb19ccc58b2bc90df7ac87d344d74a649 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 2 Mar 2018 11:18:25 +0100 Subject: [PATCH 2/5] fix signature for classes --- scripts/validate_docstrings.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 3dc2fb838ad1b..ab15bdf5705e6 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -127,7 +127,12 @@ def doc_parameters(self): @property def signature_parameters(self): - if not inspect.isfunction(self.method_obj): + if not (inspect.isfunction(self.method_obj) + or inspect.isclass(self.method_obj)): + return tuple() + if (inspect.isclass(self.method_obj) + and self.method_name.split('.')[-1] in {'dt', 'str', 'cat'}): + # accessor classes have a signature, but don't want to show this return tuple() params = tuple(inspect.signature(self.method_obj).parameters.keys()) if params and params[0] in ('self', 'cls'): From 2a1e89ec3ed764d7fcd06d5bfd5a4596b479e539 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 2 Mar 2018 11:24:01 +0100 Subject: [PATCH 3/5] add check for mentions of NDFrame or IndexOpsMixin --- scripts/validate_docstrings.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index ab15bdf5705e6..3f47c6afa0a76 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -186,6 +186,11 @@ def deprecated(self): bool(pattern.search(self.summary)) or bool(pattern.search(self.extended_summary))) + @property + def mentioned_private_classes(self): + private_classes = ['NDFrame', 'IndexOpsMixin'] + return [klass for klass in private_classes if klass in self.raw_doc] + @property def examples_errors(self): flags = doctest.NORMALIZE_WHITESPACE | doctest.IGNORE_EXCEPTION_DETAIL @@ -317,6 +322,10 @@ def validate_one(func_name): for param_err in param_errs: errs.append('\t{}'.format(param_err)) + mentioned_errs = doc.mentioned_private_classes + if mentioned_errs: + errs.append('Private classes mentioned: {}'.format(mentioned_errs)) + examples_errs = '' if not doc.examples: errs.append('No examples section found') From 7a71c220f5d8dabdd955e3a73a2a4f1f7b732823 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 2 Mar 2018 11:31:32 +0100 Subject: [PATCH 4/5] use pydoc.getdoc to get the docstring (handles indentation) --- scripts/validate_docstrings.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 3f47c6afa0a76..cfcbf2104e19d 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -23,7 +23,7 @@ import inspect import importlib import doctest -import textwrap +import pydoc try: from io import StringIO except ImportError: @@ -72,8 +72,7 @@ class Docstring: def __init__(self, method_name, method_obj): self.method_name = method_name self.method_obj = method_obj - self.raw_doc = method_obj.__doc__ or '' - self.raw_doc = textwrap.dedent(self.raw_doc) + self.raw_doc = pydoc.getdoc(method_obj) self.doc = NumpyDocString(self.raw_doc) def __len__(self): From 9e436e5b7364ee495f7b4f468cc405232b314a02 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 2 Mar 2018 12:02:29 +0100 Subject: [PATCH 5/5] updates --- scripts/validate_docstrings.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index cfcbf2104e19d..a90a55c6ce1ab 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -39,6 +39,9 @@ from numpydoc.docscrape import NumpyDocString +PRIVATE_CLASSES = ['NDFrame', 'IndexOpsMixin'] + + def _to_original_callable(obj): while True: if inspect.isfunction(obj) or inspect.isclass(obj): @@ -187,8 +190,7 @@ def deprecated(self): @property def mentioned_private_classes(self): - private_classes = ['NDFrame', 'IndexOpsMixin'] - return [klass for klass in private_classes if klass in self.raw_doc] + return [klass for klass in PRIVATE_CLASSES if klass in self.raw_doc] @property def examples_errors(self): @@ -323,7 +325,8 @@ def validate_one(func_name): mentioned_errs = doc.mentioned_private_classes if mentioned_errs: - errs.append('Private classes mentioned: {}'.format(mentioned_errs)) + errs.append('Private classes ({}) should not be mentioned in public ' + 'docstring.'.format(mentioned_errs)) examples_errs = '' if not doc.examples: