CI: run pydocstyle with our custom options by brunobeltran · Pull Request #17145 · matplotlib/matplotlib

brunobeltran · 2020-04-15T07:54:25Z

PR Summary

Fixes #17141, so that we can add extra individual errors to our flake8-docstrings (really, pydocstyle) check, especially D213, per this week's call.

Per the discussion on https://gitlab.com/pycqa/flake8-docstrings/-/issues/43, the intended solution is currently for us to list all the numpy-style error codes manually in our select block in .flake8, then add extra ones as needed.

In order to get the extra non-numpy codes to work, we have to use the (currently undocumented, but see https://gitlab.com/pycqa/flake8-docstrings/-/merge_requests/27) special catch-all flag, --docstring-convention=all.

Just for the record, the full list of non --docstring-convention=numpy error codes that we could choose to turn on is: D107, D203, D212, D213, D402, D413, D415, D416, and D417.

Their meanings can be found at http://www.pydocstyle.org/en/latest/error_codes.html.

PR Checklist

Has Pytest style unit tests
Code is Flake 8 compliant
New features are documented, with examples if plot related
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

brunobeltran · 2020-04-15T08:48:05Z

Based on the CI results, I would recommend adding D404 to the ignores for now, as I can quickly correct all the instances of D213 failing easily, but making sure no docstrings start with the word "This" is probably a separate PR.

For context, now that pydocstyle is correctly set to the numpy conventions and actually running (via flake8-docstrings) here's the results from CI:

(Again, there was nothing removed from the ignore= list, the new errors are from CI now working as it was originally supposed to)

./setupext.py:428:1: D404 First word of the docstring should not be `This`
./examples/text_labels_and_annotations/arrow_demo.py:32:1: D213 Multi-line docstring summary should start at the second line
./examples/text_labels_and_annotations/demo_annotation_box.py:1:1: D213 Multi-line docstring summary should start at the second line
./examples/statistics/confidence_ellipse.py:42:1: D405 Section name should be properly capitalized
./examples/statistics/boxplot_demo.py:195:1: D404 First word of the docstring should not be `This`
./examples/axisartist/demo_floating_axis.py:22:1: D213 Multi-line docstring summary should start at the second line
./examples/style_sheets/style_sheets_reference.py:20:1: D213 Multi-line docstring summary should start at the second line
./examples/style_sheets/style_sheets_reference.py:31:1: D213 Multi-line docstring summary should start at the second line
./examples/style_sheets/style_sheets_reference.py:44:1: D213 Multi-line docstring summary should start at the second line
./examples/style_sheets/style_sheets_reference.py:57:1: D213 Multi-line docstring summary should start at the second line
./examples/style_sheets/style_sheets_reference.py:75:1: D213 Multi-line docstring summary should start at the second line
./examples/style_sheets/style_sheets_reference.py:87:1: D213 Multi-line docstring summary should start at the second line
./examples/style_sheets/style_sheets_reference.py:107:1: D213 Multi-line docstring summary should start at the second line
./examples/scales/custom_scale.py:112:1: D404 First word of the docstring should not be `This`
./examples/specialty_plots/skewt.py:103:1: D404 First word of the docstring should not be `This`
./examples/specialty_plots/radar_chart.py:29:1: D213 Multi-line docstring summary should start at the second line
./examples/widgets/lasso_selector_demo_sgskip.py:21:1: D213 Multi-line docstring summary should start at the second line
./examples/event_handling/poly_editor.py:93:1: D404 First word of the docstring should not be `This`
./tutorials/text/text_intro.py:357:1: D213 Multi-line docstring summary should start at the second line
./lib/mpl_toolkits/mplot3d/axes3d.py:842:1: D404 First word of the docstring should not be `This`
./lib/mpl_toolkits/axes_grid1/axes_rgb.py:135:1: D213 Multi-line docstring summary should start at the second line
./lib/mpl_toolkits/axes_grid1/axes_divider.py:23:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/type1font.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/transforms.py:213:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/text.py:26:1: D213 Multi-line docstring summary should start at the second line
./lib/matplotlib/lines.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/markers.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/texmanager.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/animation.py:892:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/widgets.py:1600:1: D213 Multi-line docstring summary should start at the second line
./lib/matplotlib/contour.py:315:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/colors.py:363:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/cm.py:152:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/quiver.py:1015:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/backend_bases.py:239:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/backend_bases.py:300:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/backend_bases.py:350:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/backend_bases.py:2794:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/pyplot.py:628:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/font_manager.py:278:1: D213 Multi-line docstring summary should start at the second line
./lib/matplotlib/dates.py:565:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/dates.py:763:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/collections.py:1121:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/colorbar.py:239:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/colorbar.py:272:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/colorbar.py:1194:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/patches.py:1753:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/patches.py:1784:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/legend_handler.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tight_bbox.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tight_bbox.py:75:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/table.py:9:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tight_layout.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/mathtext.py:2278:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/_constrained_layout.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/afm.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/__init__.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/blocking_input.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/mlab.py:408:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/mlab.py:566:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tri/trirefine.py:173:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tri/triinterpolate.py:1298:1: D405 Section name should be properly capitalized
./lib/matplotlib/axes/_base.py:2765:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/axes/_base.py:2776:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/axes/_subplots.py:181:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/axes/_subplots.py:209:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/backends/backend_template.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/backends/backend_wx.py:1028:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/backends/qt_editor/figureoptions.py:173:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/test_axes.py:3794:1: D213 Multi-line docstring summary should start at the second line
./lib/matplotlib/tests/test_dates.py:270:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/test_dates.py:767:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/test_widgets.py:345:1: D213 Multi-line docstring summary should start at the second line
./lib/matplotlib/tests/test_category.py:62:1: D213 Multi-line docstring summary should start at the second line
./lib/matplotlib/tests/test_compare_images.py:46:1: D213 Multi-line docstring summary should start at the second line
./lib/matplotlib/tests/test_skew.py:93:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/test_transforms.py:16:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/test_mlab.py:23:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/test_mlab.py:154:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/tinypages/range6.py:5:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/tinypages/range6.py:10:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/testing/disable_internet.py:138:1: D213 Multi-line docstring summary should start at the second line
./lib/matplotlib/testing/jpl_units/__init__.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/cbook/__init__.py:760:1: D404 First word of the docstring should not be `This`
./doc/sphinxext/github.py:1:1: D213 Multi-line docstring summary should start at the second line
./doc/sphinxext/github.py:25:1: D213 Multi-line docstring summary should start at the second line
./doc/sphinxext/github.py:56:1: D213 Multi-line docstring summary should start at the second line
./doc/sphinxext/github.py:97:1: D213 Multi-line docstring summary should start at the second line
./doc/sphinxext/github.py:118:1: D213 Multi-line docstring summary should start at the second line
./doc/sphinxext/github.py:150:1: D213 Multi-line docstring summary should start at the second line
./doc/sphinxext/missing_references.py:1:1: D404 First word of the docstring should not be `This`
./tools/triage_tests.py:1:1: D404 First word of the docstring should not be `This`
28    D213 Multi-line docstring summary should start at the second line
62    D404 First word of the docstring should not be `This`
2     D405 Section name should be properly capitalized

.flake8

brunobeltran · 2020-04-15T20:56:11Z

Tried to remove the D404 ignore thanks to #17148, but CI correctly points out that there are a few remaining D404-nonconforming docstrings. Here's the remaining list:

./setupext.py:428:1: D404 First word of the docstring should not be `This`
./examples/event_handling/poly_editor.py:93:1: D404 First word of the docstring should not be `This`
./examples/scales/custom_scale.py:112:1: D404 First word of the docstring should not be `This`
./examples/statistics/boxplot_demo.py:195:1: D404 First word of the docstring should not be `This`
./examples/specialty_plots/skewt.py:103:1: D404 First word of the docstring should not be `This`
./doc/sphinxext/missing_references.py:1:1: D404 First word of the docstring should not be `This`
./tools/triage_tests.py:1:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/colorbar.py:239:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/colorbar.py:272:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/colorbar.py:299:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/colorbar.py:1192:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/backend_bases.py:2790:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/test_transforms.py:16:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/test_dates.py:270:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/test_dates.py:767:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/test_skew.py:93:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/test_mlab.py:23:1: D404 First word of the docstring should not be `This`
./lib/matplotlib/tests/test_mlab.py:154:1: D404 First word of the docstring should not be `This`
18    D404 First word of the docstring should not be `This`

brunobeltran · 2020-04-16T09:42:55Z

Looks like this commit should wait on #17143 (or vice-versa, that PR should add --docstring-convention=all to the flake8 call).

brunobeltran force-pushed the flake8-docstrings-select branch from 3b2e153 to b859a67 Compare April 15, 2020 08:00

anntzer reviewed Apr 15, 2020

View reviewed changes

.flake8 Show resolved Hide resolved

anntzer mentioned this pull request Apr 15, 2020

Fix most instances of D404 ("docstring should not start with 'this'"). #17148

Merged

6 tasks

CI: run pydocstyle with our custom options

c7e83ba

brunobeltran force-pushed the flake8-docstrings-select branch from 70e7dff to ff9da09 Compare April 15, 2020 19:38

DOCS/CI: fix D213 so CI passes, ignore D404

f1b8705

brunobeltran force-pushed the flake8-docstrings-select branch from ff9da09 to f1b8705 Compare April 15, 2020 20:55

brunobeltran mentioned this pull request Apr 15, 2020

flake8-docstrings does not check all of our requirements #17141

Closed

timhoffm approved these changes Apr 16, 2020

View reviewed changes

QuLogic approved these changes Apr 16, 2020

View reviewed changes

QuLogic merged commit 52e04f5 into matplotlib:master Apr 16, 2020

QuLogic added this to the v3.3.0 milestone Apr 17, 2020

QuLogic mentioned this pull request Apr 17, 2020

Move linting to GitHub Actions with reviewdog. #17143

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

CI: run pydocstyle with our custom options#17145

CI: run pydocstyle with our custom options#17145
QuLogic merged 2 commits intomatplotlib:masterfrom
brunobeltran:flake8-docstrings-select

brunobeltran commented Apr 15, 2020 •

edited

Loading

Uh oh!

brunobeltran commented Apr 15, 2020

Uh oh!

Uh oh!

brunobeltran commented Apr 15, 2020

Uh oh!

brunobeltran commented Apr 16, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

brunobeltran commented Apr 15, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

PR Checklist

Uh oh!

brunobeltran commented Apr 15, 2020

Uh oh!

Uh oh!

brunobeltran commented Apr 15, 2020

Uh oh!

brunobeltran commented Apr 16, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

brunobeltran commented Apr 15, 2020 •

edited

Loading