Skip to content

validate_docstrings improvements #25122

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

validate_docstrings improvements #25122

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f5e89f1
validate_docstrings outputs warning/error codes
kynan Feb 3, 2019
7bdefdb
Add --list-errors flag to valid_docstrings
kynan Feb 3, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 40 additions & 22 deletions scripts/validate_docstrings.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@
except ImportError:
from cStringIO import StringIO

# Template backend makes matplotlib to not plot anything. This is useful
# to avoid that plot windows are open from the doctests while running the
# Template backend makes matplotlib not plot anything. This is useful
# to avoid plot windows opening from the doctests while running the
# script. Setting here before matplotlib is loaded.
# We don't warn for the number of open plots, as none is actually being opened
os.environ['MPLBACKEND'] = 'Template'
Expand Down Expand Up @@ -837,7 +837,14 @@ def validate_all(prefix, ignore_deprecated=False):
return result


def main(func_name, prefix, errors, output_format, ignore_deprecated):
def main(func_name, prefix, errors, output_format, ignore_deprecated,
list_errors):

if list_errors:
for code, msg in ERROR_MSGS.items():
sys.stdout.write('[{}] {}\n'.format(code, msg))
return 0

def header(title, width=80, char='#'):
full_line = char * width
side_len = (width - len(title) - 2) // 2
Expand Down Expand Up @@ -897,14 +904,14 @@ def header(title, width=80, char='#'):
for err_code, err_desc in result['errors']:
# Failing examples are printed at the end
if err_code == 'EX02':
sys.stderr.write('\tExamples do not pass tests\n')
sys.stderr.write(' [EX02] Examples do not pass tests\n')
continue
sys.stderr.write('\t{}\n'.format(err_desc))
sys.stderr.write(' [{}] {}\n'.format(err_code, err_desc))
if result['warnings']:
sys.stderr.write('{} Warnings found:\n'.format(
len(result['warnings'])))
for wrn_code, wrn_desc in result['warnings']:
sys.stderr.write('\t{}\n'.format(wrn_desc))
sys.stderr.write(' [{}] {}\n'.format(wrn_code, wrn_desc))

if not result['errors']:
sys.stderr.write('Docstring for "{}" correct. :)\n'.format(
Expand All @@ -928,27 +935,38 @@ def header(title, width=80, char='#'):
nargs='?',
default=None,
help=func_help)
argparser.add_argument('--format', default='default', choices=format_opts,
argparser.add_argument('--format',
default='default',
choices=format_opts,
help='format of the output when validating '
'multiple docstrings (ignored when validating one).'
'It can be {}'.format(str(format_opts)[1:-1]))
argparser.add_argument('--prefix', default=None, help='pattern for the '
'docstring names, in order to decide which ones '
'will be validated. A prefix "pandas.Series.str.'
'will make the script validate all the docstrings'
'of methods starting by this pattern. It is '
'ignored if parameter function is provided')
argparser.add_argument('--errors', default=None, help='comma separated '
'list of error codes to validate. By default it '
'validates all errors (ignored when validating '
'a single docstring)')
argparser.add_argument('--ignore_deprecated', default=False,
action='store_true', help='if this flag is set, '
'deprecated objects are ignored when validating '
'all docstrings')
argparser.add_argument('--prefix',
default=None,
help='pattern for the docstring names, in order '
'to decide which ones will be validated. A prefix '
'"pandas.Series.str." will make the script '
'validate all the docstrings of methods starting '
'by this pattern. It is ignored if parameter '
'function is provided')
argparser.add_argument('--errors',
default=None,
help='comma separated list of error codes to '
'validate. By default it validates all errors '
'(ignored when validating a single docstring)')
argparser.add_argument('--ignore_deprecated',
default=False,
action='store_true',
help='if this flag is set, deprecated objects are '
'ignored when validating all docstrings')
argparser.add_argument('--list-errors',
default=False,
action='store_true',
help='list error codes / descriptions checked for')

args = argparser.parse_args()
sys.exit(main(args.function, args.prefix,
args.errors.split(',') if args.errors else None,
args.format,
args.ignore_deprecated))
args.ignore_deprecated,
args.list_errors))