Merge pull request #17145 from brunobeltran/flake8-docstrings-select

QuLogic · web-flow · commit 52e04f5d87c5 · 2020-04-16T17:16:14.000-04:00
CI: run pydocstyle with our custom options
diff --git a/.flake8 b/.flake8
@@ -1,7 +1,19 @@
 [flake8]
 max-line-length = 79
+select =
+    # flake8 default
+    C90, E, F, W,
+    # docstring-convention=numpy
+    D100, D101, D102, D103, D104, D105, D106,
+    D200, D201, D202, D204, D205, D206, D207, D208,
+    D209, D210, D211, D214, D215,
+    D300, D301, D302,
+    D400, D401, D403, D404, D405, D406, D407, D408,
+    D409, D410, D411, D412, D414,
+    # matplotlib-specific extra pydocstyle errors
+    D213,
 ignore =
-    # Normal default
+    # flake8 default
     E121,E123,E126,E226,E24,E704,W503,W504,
     # Additional ignores:
     E122, E127, E131,
@@ -14,8 +26,8 @@ ignore =
     # pydocstyle
     D100, D101, D102, D103, D104, D105, D106, D107,
     D200, D202, D203, D204, D205, D207, D212,
-    D301
-    D400, D401, D402, D403, D413,
+    D301,
+    D400, D401, D402, D403, D404, D413,
 
 exclude =
     .git
diff --git a/.travis.yml b/.travis.yml
@@ -192,7 +192,7 @@ script:
     fi
   - |
     if [[ $RUN_FLAKE8 == 1 ]]; then
-      flake8 --statistics && echo "Flake8 passed without any issues!"
+      flake8 --docstring-convention=all --statistics && echo "Flake8 passed without any issues!"
     fi
 
 before_cache: |
diff --git a/doc/sphinxext/github.py b/doc/sphinxext/github.py
@@ -1,4 +1,5 @@
-"""Define text roles for GitHub
+"""
+Define text roles for GitHub.
 
 * ghissue - Issue
 * ghpull - Pull Request
@@ -22,7 +23,8 @@
 
 
 def make_link_node(rawtext, app, type, slug, options):
-    """Create a link to a github resource.
+    """
+    Create a link to a github resource.
 
     :param rawtext: Text being replaced with link node.
     :param app: Sphinx application context
@@ -53,7 +55,8 @@ def make_link_node(rawtext, app, type, slug, options):
 
 
 def ghissue_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-    """Link to a GitHub issue.
+    """
+    Link to a GitHub issue.
 
     Returns 2 part tuple containing list of nodes to insert into the
     document and a list of system messages.  Both are allowed to be
@@ -94,7 +97,8 @@ def ghissue_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
 
 
 def ghuser_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-    """Link to a GitHub user.
+    """
+    Link to a GitHub user.
 
     Returns 2 part tuple containing list of nodes to insert into the
     document and a list of system messages.  Both are allowed to be
@@ -115,7 +119,8 @@ def ghuser_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
 
 def ghcommit_role(
         name, rawtext, text, lineno, inliner, options={}, content=[]):
-    """Link to a GitHub commit.
+    """
+    Link to a GitHub commit.
 
     Returns 2 part tuple containing list of nodes to insert into the
     document and a list of system messages.  Both are allowed to be
@@ -147,7 +152,8 @@ def ghcommit_role(
 
 
 def setup(app):
-    """Install the plugin.
+    """
+    Install the plugin.
 
     :param app: Sphinx application context.
     """
diff --git a/examples/axisartist/demo_floating_axis.py b/examples/axisartist/demo_floating_axis.py
@@ -19,8 +19,7 @@
 
 
 def curvelinear_test2(fig):
-    """Polar projection, but in a rectangular box.
-    """
+    """Polar projection, but in a rectangular box."""
     # see demo_curvelinear_grid.py for details
     tr = Affine2D().scale(np.pi / 180., 1.) + PolarAxes.PolarTransform()
 
diff --git a/examples/specialty_plots/radar_chart.py b/examples/specialty_plots/radar_chart.py
@@ -26,7 +26,8 @@
 
 
 def radar_factory(num_vars, frame='circle'):
-    """Create a radar chart with `num_vars` axes.
+    """
+    Create a radar chart with `num_vars` axes.
 
     This function creates a RadarAxes projection and registers it.
 
diff --git a/examples/statistics/confidence_ellipse.py b/examples/statistics/confidence_ellipse.py
@@ -53,13 +53,12 @@ def confidence_ellipse(x, y, ax, n_std=3.0, facecolor='none', **kwargs):
     n_std : float
         The number of standard deviations to determine the ellipse's radiuses.
 
+    **kwargs
+        Forwarded to `~matplotlib.patches.Ellipse`
+
     Returns
     -------
     matplotlib.patches.Ellipse
-
-    Other parameters
-    ----------------
-    kwargs : `~matplotlib.patches.Patch` properties
     """
     if x.size != y.size:
         raise ValueError("x and y must be the same size")
diff --git a/examples/style_sheets/style_sheets_reference.py b/examples/style_sheets/style_sheets_reference.py
@@ -17,8 +17,7 @@
 
 
 def plot_scatter(ax, prng, nb_samples=100):
-    """Scatter plot.
-    """
+    """Scatter plot."""
     for mu, sigma, marker in [(-.5, 0.75, 'o'), (0.75, 1., 's')]:
         x, y = prng.normal(loc=mu, scale=sigma, size=(2, nb_samples))
         ax.plot(x, y, ls='none', marker=marker)
@@ -28,8 +27,7 @@ def plot_scatter(ax, prng, nb_samples=100):
 
 
 def plot_colored_sinusoidal_lines(ax):
-    """Plot sinusoidal lines with colors following the style color cycle.
-    """
+    """Plot sinusoidal lines with colors following the style color cycle."""
     L = 2 * np.pi
     x = np.linspace(0, L)
     nb_colors = len(plt.rcParams['axes.prop_cycle'])
@@ -41,8 +39,7 @@ def plot_colored_sinusoidal_lines(ax):
 
 
 def plot_bar_graphs(ax, prng, min_value=5, max_value=25, nb_samples=5):
-    """Plot two bar graphs side by side, with letters as x-tick labels.
-    """
+    """Plot two bar graphs side by side, with letters as x-tick labels."""
     x = np.arange(nb_samples)
     ya, yb = prng.randint(min_value, max_value, size=(2, nb_samples))
     width = 0.25
@@ -54,7 +51,8 @@ def plot_bar_graphs(ax, prng, min_value=5, max_value=25, nb_samples=5):
 
 
 def plot_colored_circles(ax, prng, nb_samples=15):
-    """Plot circle patches.
+    """
+    Plot circle patches.
 
     NB: draws a fixed amount of samples, rather than using the length of
     the color cycle, because different styles may have different numbers
@@ -72,8 +70,7 @@ def plot_colored_circles(ax, prng, nb_samples=15):
 
 
 def plot_image_and_patch(ax, prng, size=(20, 20)):
-    """Plot an image with random values and superimpose a circular patch.
-    """
+    """Plot an image with random values and superimpose a circular patch."""
     values = prng.random_sample(size=size)
     ax.imshow(values, interpolation='none')
     c = plt.Circle((5, 5), radius=5, label='patch')
@@ -84,8 +81,7 @@ def plot_image_and_patch(ax, prng, size=(20, 20)):
 
 
 def plot_histograms(ax, prng, nb_samples=10000):
-    """Plot 4 histograms and a text annotation.
-    """
+    """Plot 4 histograms and a text annotation."""
     params = ((10, 10), (4, 12), (50, 12), (6, 55))
     for a, b in params:
         values = prng.beta(a, b, size=nb_samples)
@@ -104,8 +100,7 @@ def plot_histograms(ax, prng, nb_samples=10000):
 
 
 def plot_figure(style_label=""):
-    """Setup and plot the demonstration figure with a given style.
-    """
+    """Setup and plot the demonstration figure with a given style."""
     # Use a dedicated RandomState instance to draw the same "random" values
     # across the different figures.
     prng = np.random.RandomState(96917002)
diff --git a/examples/text_labels_and_annotations/arrow_demo.py b/examples/text_labels_and_annotations/arrow_demo.py
@@ -29,7 +29,8 @@ def make_arrow_plot(data, size=4, display='length', shape='right',
                     head_starts_at_zero=True,
                     rate_labels=lettered_bases_to_rates,
                     **kwargs):
-    """Makes an arrow plot.
+    """
+    Makes an arrow plot.
 
     Parameters
     ----------
diff --git a/examples/text_labels_and_annotations/demo_annotation_box.py b/examples/text_labels_and_annotations/demo_annotation_box.py
@@ -1,4 +1,5 @@
-"""===================
+"""
+===================
 Demo Annotation Box
 ===================
 
diff --git a/examples/widgets/lasso_selector_demo_sgskip.py b/examples/widgets/lasso_selector_demo_sgskip.py
@@ -18,7 +18,8 @@
 
 
 class SelectFromCollection:
-    """Select indices from a matplotlib collection using `LassoSelector`.
+    """
+    Select indices from a matplotlib collection using `LassoSelector`.
 
     Selected indices are saved in the `ind` attribute. This tool fades out the
     points that are not part of the selection (i.e., reduces their alpha
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
@@ -275,8 +275,7 @@ def _call_fc_list():
 
 
 def get_fontconfig_fonts(fontext='ttf'):
-    """List the font filenames known to `fc-list` having the given extension.
-    """
+    """List font filenames known to `fc-list` having the given extension."""
     fontext = ['.' + ext for ext in get_fontext_synonyms(fontext)]
     return [fname for fname in _call_fc_list()
             if Path(fname).suffix.lower() in fontext]
diff --git a/lib/matplotlib/testing/disable_internet.py b/lib/matplotlib/testing/disable_internet.py
@@ -135,8 +135,10 @@ def turn_on_internet(verbose=False):
 
 @contextlib.contextmanager
 def no_internet(verbose=False):
-    """Context manager to temporarily disable internet access (if not already
-    disabled).  If it was already disabled before entering the context manager
+    """
+    Temporarily disables internet access (if not already disabled).
+
+    If it was already disabled before entering the context manager
     (i.e. `turn_off_internet` was called previously) then this is a no-op and
     leaves internet access disabled until a manual call to `turn_on_internet`.
     """
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -3791,8 +3791,7 @@ def test_eventplot_defaults():
     ('red', (0, 1, 0), None, (1, 0, 1, 0.5)),  # a tricky case mixing types
 ])
 def test_eventplot_colors(colors):
-    """Test the *colors* parameter of eventplot. Inspired by the issue #8193.
-    """
+    """Test the *colors* parameter of eventplot. Inspired by issue #8193."""
     data = [[i] for i in range(4)]  # 4 successive events of different nature
 
     # Build the list of the expected colors
diff --git a/lib/matplotlib/tests/test_category.py b/lib/matplotlib/tests/test_category.py
@@ -59,7 +59,8 @@ def __init__(self, units):
 
 
 class TestStrCategoryConverter:
-    """Based on the pandas conversion and factorization tests:
+    """
+    Based on the pandas conversion and factorization tests:
 
     ref: /pandas/tseries/tests/test_converter.py
          /pandas/tests/test_algos.py:TestFactorize
diff --git a/lib/matplotlib/tests/test_compare_images.py b/lib/matplotlib/tests/test_compare_images.py
@@ -43,7 +43,8 @@
         ('all128.png', 'all127.png', 0, 1),
     ])
 def test_image_comparison_expect_rms(im1, im2, tol, expect_rms):
-    """Compare two images, expecting a particular RMS error.
+    """
+    Compare two images, expecting a particular RMS error.
 
     im1 and im2 are filenames relative to the baseline_dir directory.
 
diff --git a/lib/matplotlib/tests/test_widgets.py b/lib/matplotlib/tests/test_widgets.py
@@ -342,7 +342,8 @@ def test_slider_horizontal_vertical():
 
 
 def check_polygon_selector(event_sequence, expected_result, selections_count):
-    """Helper function to test Polygon Selector
+    """
+    Helper function to test Polygon Selector.
 
     Parameters
     ----------
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -23,8 +23,7 @@
 
 @contextlib.contextmanager
 def _wrap_text(textobj):
-    """Temporarily inserts newlines to the text if the wrap option is enabled.
-    """
+    """Temporarily inserts newlines if the wrap option is enabled."""
     if textobj.get_wrap():
         old_text = textobj.get_text()
         try:
diff --git a/lib/matplotlib/tri/triinterpolate.py b/lib/matplotlib/tri/triinterpolate.py
@@ -1308,27 +1308,24 @@ def _cg(A, b, x0=None, tol=1.e-10, maxiter=1000):
     A : _Sparse_Matrix_coo
         *A* must have been compressed before by compress_csc or
         compress_csr method.
-
     b : array
         Right hand side of the linear system.
+    x0 : array, optional
+        Starting guess for the solution. Defaults to the zero vector.
+    tol : float, optional
+        Tolerance to achieve. The algorithm terminates when the relative
+        residual is below tol. Default is 1e-10.
+    maxiter : int, optional
+        Maximum number of iterations.  Iteration will stop after *maxiter*
+        steps even if the specified tolerance has not been achieved. Defaults
+        to 1000.
 
     Returns
     -------
     x : array
         The converged solution.
     err : float
         The absolute error np.linalg.norm(A.dot(x) - b)
-
-    Other parameters
-    ----------------
-    x0 : array
-        Starting guess for the solution.
-    tol : float
-        Tolerance to achieve. The algorithm terminates when the relative
-        residual is below tol.
-    maxiter : int
-        Maximum number of iterations.  Iteration will stop after *maxiter*
-        steps even if the specified tolerance has not been achieved.
     """
     n = b.size
     assert A.n == n
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -1597,8 +1597,7 @@ def on_key_press(self, event):
             self._on_key_press(event)
 
     def _on_key_press(self, event):
-        """Key press event handler - use for widget-specific key press actions.
-        """
+        """Key press event handler - for widget-specific key press actions."""
 
     def on_key_release(self, event):
         """Key release event handler and validator."""
diff --git a/lib/mpl_toolkits/axes_grid1/axes_rgb.py b/lib/mpl_toolkits/axes_grid1/axes_rgb.py
@@ -132,8 +132,7 @@ def _config_axes(self, line_color='w', marker_edge_color='w'):
 
     @cbook.deprecated("3.3")
     def add_RGB_to_figure(self):
-        """Add the red, green and blue axes to the RGB composite's axes figure
-        """
+        """Add red, green and blue axes to the RGB composite's axes figure."""
         self.RGB.get_figure().add_axes(self.R)
         self.RGB.get_figure().add_axes(self.G)
         self.RGB.get_figure().add_axes(self.B)
diff --git a/tutorials/text/text_intro.py b/tutorials/text/text_intro.py
@@ -354,8 +354,7 @@
 
 
 def formatoddticks(x, pos):
-    """Format odd tick positions
-    """
+    """Format odd tick positions."""
     if x % 2:
         return '%1.2f' % x
     else:
