🎨 share docs

Author: MarcoGorelli

pandas/plotting/_core.py

@@ -386,6 +386,45 @@ def hist_frame(
 """
 
 
+_bar_or_line_doc = """\
+Parameters
+----------
+x : label or position, optional
+    Allows plotting of one column versus another. If not specified,
+    the index of the DataFrame is used.
+y : label or position, optional
+    Allows plotting of one column versus another. If not specified,
+    all numerical columns are used.
+color : str, array_like, or dict, optional
+    The color for each of the DataFrame's columns. Possible values are:
+
+    - A single color string referred to by name, RGB or RGBA code,
+        for instance 'red' or '#a98d19'.
+
+    - A sequence of color strings referred to by name, RGB or RGBA
+        code, which will be used for each column recursively. For
+        instance ['green','yellow'] each column's %(kind)s will be filled in
+        green or yellow, alternatively.
+
+    - A dict of the form {column name : color}, so that each column will be
+        colored accordingly. For example, if your columns are called `a` and `b`,
+        then passing {'a': 'green', 'b': 'red'} will color %(kind)ss for column `a` in
+        green and %(kind)ss for column `b` in red.
+
+    .. versionadded:: 1.1.0
+
+**kwargs
+    Additional keyword arguments are documented in
+    :meth:`DataFrame.plot`.
+
+Returns
+-------
+matplotlib.axes.Axes or np.ndarray of them
+    An ndarray is returned with one :class:`matplotlib.axes.Axes`
+    per column when ``subplots=True``.
+"""
+
+
 @Substitution(backend="")
 @Appender(_boxplot_doc)
 def boxplot(
@@ -847,46 +886,8 @@ def __call__(self, *args, **kwargs):
 
         return plot_backend.plot(data, kind=kind, **kwargs)
 
-    def line(self, x=None, y=None, **kwargs):
+    @Appender(
         """
-        Plot Series or DataFrame as lines.
-
-        This function is useful to plot lines using DataFrame's values
-        as coordinates.
-
-        Parameters
-        ----------
-        x : int or str, optional
-            Columns to use for the horizontal axis.
-            Either the location or the label of the columns to be used.
-            By default, it will use the DataFrame indices.
-        y : int, str, or list of them, optional
-            The values to be plotted.
-            Either the location or the label of the columns to be used.
-            By default, it will use the remaining DataFrame numeric columns.
-        color : str, int, array_like, or dict, optional
-            The color for each of the DataFrame's columns. Possible values are:
-
-            - A single color string referred to by name, RGB or RGBA code,
-              for instance 'red' or '#a98d19'.
-
-            - A sequence of color strings referred to by name, RGB or RGBA
-              code, which will be used for each column recursively. For
-              instance ['green','yellow'] each column's line will be coloured in
-              green or yellow, alternatively.
-
-            - A dict of the form {column name : color}, so that each column will be
-              colored accordingly. For example, if your columns are called `a` and `b`,
-              then passing {'a': 'green', 'b': 'red'} will color lines for column `a` in
-              green and lines for column `b` in red.
-        **kwargs
-            Keyword arguments to pass on to :meth:`DataFrame.plot`.
-
-        Returns
-        -------
-        :class:`matplotlib.axes.Axes` or :class:`numpy.ndarray`
-            Return an ndarray when ``subplots=True``.
-
         See Also
         --------
         matplotlib.pyplot.plot : Plot y versus x as lines and/or markers.
@@ -939,51 +940,20 @@ def line(self, x=None, y=None, **kwargs):
 
             >>> lines = df.plot.line(x='pig', y='horse')
         """
-        return self(kind="line", x=x, y=y, **kwargs)
-
-    def bar(self, x=None, y=None, **kwargs):
+    )
+    @Substitution(kind="line")
+    @Appender(_bar_or_line_doc)
+    def line(self, x=None, y=None, **kwargs):
         """
-        Vertical bar plot.
-
-        A bar plot is a plot that presents categorical data with
-        rectangular bars with lengths proportional to the values that they
-        represent. A bar plot shows comparisons among discrete categories. One
-        axis of the plot shows the specific categories being compared, and the
-        other axis represents a measured value.
-
-        Parameters
-        ----------
-        x : label or position, optional
-            Allows plotting of one column versus another. If not specified,
-            the index of the DataFrame is used.
-        y : label or position, optional
-            Allows plotting of one column versus another. If not specified,
-            all numerical columns are used.
-        color : str, int, array_like, or dict, optional
-            The color for each of the DataFrame's columns. Possible values are:
-
-            - A single color string referred to by name, RGB or RGBA code,
-              for instance 'red' or '#a98d19'.
-
-            - A sequence of color strings referred to by name, RGB or RGBA
-              code, which will be used for each column recursively. For
-              instance ['green','yellow'] each column's bar will be filled in
-              green or yellow, alternatively.
-
-            - A dict of the form {column name : color}, so that each column will be
-              colored accordingly. For example, if your columns are called `a` and `b`,
-              then passing {'a': 'green', 'b': 'red'} will color bars for column `a` in
-              green and bars for column `b` in red.
-        **kwargs
-            Additional keyword arguments are documented in
-            :meth:`DataFrame.plot`.
+        Plot Series or DataFrame as lines.
 
-        Returns
-        -------
-        matplotlib.axes.Axes or np.ndarray of them
-            An ndarray is returned with one :class:`matplotlib.axes.Axes`
-            per column when ``subplots=True``.
+        This function is useful to plot lines using DataFrame's values
+        as coordinates.
+        """
+        return self(kind="line", x=x, y=y, **kwargs)
 
+    @Appender(
+        """
         See Also
         --------
         DataFrame.plot.barh : Horizontal bar plot.
@@ -1049,47 +1019,24 @@ def bar(self, x=None, y=None, **kwargs):
             :context: close-figs
 
             >>> ax = df.plot.bar(x='lifespan', rot=0)
+    """
+    )
+    @Substitution(kind="bar")
+    @Appender(_bar_or_line_doc)
+    def bar(self, x=None, y=None, **kwargs):
         """
-        return self(kind="bar", x=x, y=y, **kwargs)
-
-    def barh(self, x=None, y=None, **kwargs):
-        """
-        Make a horizontal bar plot.
+        Vertical bar plot.
 
-        A horizontal bar plot is a plot that presents quantitative data with
+        A bar plot is a plot that presents categorical data with
         rectangular bars with lengths proportional to the values that they
         represent. A bar plot shows comparisons among discrete categories. One
         axis of the plot shows the specific categories being compared, and the
         other axis represents a measured value.
+        """
+        return self(kind="bar", x=x, y=y, **kwargs)
 
-        Parameters
-        ----------
-        x : label or position, default DataFrame.index
-            Column to be used for categories.
-        y : label or position, default All numeric columns in dataframe
-            Columns to be plotted from the DataFrame.
-        color : str, int, array_like, or dict, optional
-            The color for each of the DataFrame's columns. Possible values are:
-
-            - A single color string referred to by name, RGB or RGBA code,
-              for instance 'red' or '#a98d19'.
-
-            - A sequence of color strings referred to by name, RGB or RGBA
-              code, which will be used for each column recursively. For
-              instance ['green','yellow'] each column's bar will be filled in
-              green or yellow, alternatively.
-
-            - A dict of the form {column name : color}, so that each column will be
-              colored accordingly. For example, if your columns are called `a` and `b`,
-              then passing {'a': 'green', 'b': 'red'} will color bars for column `a` in
-              green and bars for column `b` in red.
-        **kwargs
-            Keyword arguments to pass on to :meth:`DataFrame.plot`.
-
-        Returns
-        -------
-        :class:`matplotlib.axes.Axes` or numpy.ndarray of them
-
+    @Appender(
+        """
         See Also
         --------
         DataFrame.plot.bar: Vertical bar plot.
@@ -1151,6 +1098,19 @@ def barh(self, x=None, y=None, **kwargs):
             >>> df = pd.DataFrame({'speed': speed,
             ...                    'lifespan': lifespan}, index=index)
             >>> ax = df.plot.barh(x='lifespan')
+    """
+    )
+    @Substitution(kind="bar")
+    @Appender(_bar_or_line_doc)
+    def barh(self, x=None, y=None, **kwargs):
+        """
+        Make a horizontal bar plot.
+
+        A horizontal bar plot is a plot that presents quantitative data with
+        rectangular bars with lengths proportional to the values that they
+        represent. A bar plot shows comparisons among discrete categories. One
+        axis of the plot shows the specific categories being compared, and the
+        other axis represents a measured value.
         """
         return self(kind="barh", x=x, y=y, **kwargs)