Repository: pandas-dev/pandas

Issue:
DOC: Fix the docstring of quantile in pandas/core/frame.py
pandas docstring are expected to follow the format defined in https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html

This includes among other things:
- There is a short description fitting in one line (there can be a longer one after that).
- The description of the parameters, the returns section, and the see also items, starts with a capital letter and ends with a period.
- In the Return section there is no name before the type (e.g. `transformed : Series`) but just the type (e.g. `Series`) in the first line.
- The examples are valid PEP-8 code, and when executed, they produce the shown input.

We should make the required adjustments in the docstring of the function `quantile` in `pandas/core/frame.py`.

We should validate the docstring with our validator (which does not validate all the formats, but some):
- `./scripts/validate_docstrings.py pandas.DataFrame.quantile`

And we should validate the PEP-8 of the examples (note that the next command will validate the PEP-8 of all examples, just make sure that none of the shown is in the function being addressed, the rest will be fixed in separate issues):
- `flake8 --doctests pandas/core/frame.py`


Discussion:
I would like to grab this issue !

Resolving patch:
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -7463,15 +7463,13 @@ def quantile(self, q=0.5, axis=0, numeric_only=True,
         Parameters
         ----------
         q : float or array-like, default 0.5 (50% quantile)
-            0 <= q <= 1, the quantile(s) to compute
+            Value between 0 <= q <= 1, the quantile(s) to compute.
         axis : {0, 1, 'index', 'columns'} (default 0)
-            0 or 'index' for row-wise, 1 or 'columns' for column-wise
-        numeric_only : boolean, default True
+            Equals 0 or 'index' for row-wise, 1 or 'columns' for column-wise.
+        numeric_only : bool, default True
             If False, the quantile of datetime and timedelta data will be
-            computed as well
+            computed as well.
         interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
-            .. versionadded:: 0.18.0
-
             This optional parameter specifies the interpolation method to use,
             when the desired quantile lies between two data points `i` and `j`:
 
@@ -7482,6 +7480,8 @@ def quantile(self, q=0.5, axis=0, numeric_only=True,
             * nearest: `i` or `j` whichever is nearest.
             * midpoint: (`i` + `j`) / 2.
 
+            .. versionadded:: 0.18.0
+
         Returns
         -------
         quantiles : Series or DataFrame
@@ -7494,18 +7494,17 @@ def quantile(self, q=0.5, axis=0, numeric_only=True,
 
         See Also
         --------
-        pandas.core.window.Rolling.quantile
-        numpy.percentile
+        core.window.Rolling.quantile: Rolling quantile.
+        numpy.percentile: Numpy function to compute the percentile.
 
         Examples
         --------
-
         >>> df = pd.DataFrame(np.array([[1, 1], [2, 10], [3, 100], [4, 100]]),
-                              columns=['a', 'b'])
+        ...                   columns=['a', 'b'])
         >>> df.quantile(.1)
         a    1.3
         b    3.7
-        dtype: float64
+        Name: 0.1, dtype: float64
         >>> df.quantile([.1, .5])
                a     b
         0.1  1.3   3.7
@@ -7515,10 +7514,10 @@ def quantile(self, q=0.5, axis=0, numeric_only=True,
         datetime and timedelta data.
 
         >>> df = pd.DataFrame({'A': [1, 2],
-                               'B': [pd.Timestamp('2010'),
-                                     pd.Timestamp('2011')],
-                               'C': [pd.Timedelta('1 days'),
-                                     pd.Timedelta('2 days')]})
+        ...                    'B': [pd.Timestamp('2010'),
+        ...                          pd.Timestamp('2011')],
+        ...                    'C': [pd.Timedelta('1 days'),
+        ...                          pd.Timedelta('2 days')]})
         >>> df.quantile(0.5, numeric_only=False)
         A                    1.5
         B    2010-07-02 12:00:00


Test patch: