Per the discussion onhttps://gitlab.com/pycqa/flake8-docstrings/-/issues/43, the intended solution is currently for us to list all thenumpy-style error codes manually in ourselect 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 seehttps://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 athttp://www.pydocstyle.org/en/latest/error_codes.html.

PR Checklist

Has Pytest style unit tests
Code isFlake 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 force-pushed theflake8-docstrings-select branch from3b2e153 tob859a67Compare

April 15, 2020 08:00

Copy link

ContributorAuthor

brunobeltran commentedApr 15, 2020

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

For context, now thatpydocstyle is correctly set to thenumpy conventions and actually running (viaflake8-docstrings) here's the results fromCI:

(Again, there was nothing removed from theignore= 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 line62    D404 First word of the docstring should not be `This`2     D405 Section name should be properly capitalized

anntzer reviewed

Apr 15, 2020

View reviewed changes

.flake8Show resolvedHide 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 theflake8-docstrings-select branch from70e7dff toff9da09Compare

April 15, 2020 19:38

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

f1b8705

brunobeltran force-pushed theflake8-docstrings-select branch fromff9da09 tof1b8705Compare

April 15, 2020 20:55

Copy link

ContributorAuthor

brunobeltran commentedApr 15, 2020

Tried to remove theD404 ignore thanks to#17148, but CI correctly points out that there are a few remainingD404-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`