Repository: pandas-dev/pandas
Pull request: DOC: Capitalize docstring summaries of Series
Updated documentation to resolve SS02 errors in pandas.Series

- [x] closes #23641
- [x] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Problem statement:
DOC: Capitalize docstring summaries of Series
Our standard is to start the docstrings with a capital letter (and finish them with a period).

We'll shortly add a check to make sure that new contributions follow this standard. But before we can do that, we need to fix the many cases that are already wrong.

In this issue we should fix all the cases of methods of Series. This is the command to generate them (which should return nothing after the fix), and the list of current issues.
```
$ ./scripts/validate_docstrings.py --prefix=pandas.Series --errors=SS02
pandas.Series.dtype: Summary does not start with a capital letter
pandas.Series.ftype: Summary does not start with a capital letter
pandas.Series.shape: Summary does not start with a capital letter
pandas.Series.nbytes: Summary does not start with a capital letter
pandas.Series.ndim: Summary does not start with a capital letter
pandas.Series.size: Summary does not start with a capital letter
pandas.Series.strides: Summary does not start with a capital letter
pandas.Series.itemsize: Summary does not start with a capital letter
pandas.Series.base: Summary does not start with a capital letter
pandas.Series.T: Summary does not start with a capital letter
pandas.Series.hasnans: Summary does not start with a capital letter
pandas.Series.flags: Summary does not start with a capital letter
pandas.Series.dtypes: Summary does not start with a capital letter
pandas.Series.ftypes: Summary does not start with a capital letter
pandas.Series.data: Summary does not start with a capital letter
pandas.Series.get_values: Summary does not start with a capital letter
pandas.Series.item: Summary does not start with a capital letter
pandas.Series.argmin: Summary does not start with a capital letter
pandas.Series.argmax: Summary does not start with a capital letter
pandas.Series.dt.round: Summary does not start with a capital letter
pandas.Series.dt.floor: Summary does not start with a capital letter
pandas.Series.dt.ceil: Summary does not start with a capital letter
pandas.Series.to_msgpack: Summary does not start with a capital letter
pandas.Series.sparse: Summary does not start with a capital letter
pandas.Series.transpose: Summary does not start with a capital letter
```

In some cases the problem is that there is a deprecated directive `.. deprecated::` at the beginning of te docstring. This is wrong too, and the deprecation should be after the short summary (the first line/paragraph of the summary).

While this issue is mainly to make the first letter in the summary a capital letter, for the cases where this is fix, would be nice to also add a period at the end of the paragraph, if there is not one already.

Hints from issue discussion:
I will work on this as part of the Pycon CA sprint 👍
Excellent, just ping us if you need any help.
I'm also working on this ticket. I've talked with @dat-boris he's ok with me continuing working on it.
@datapythonista 
I have fixed everything except for the following warning messages:

* pandas.Series.argmin: Summary does not start with a capital letter
* pandas.Series.argmax: Summary does not start with a capital letter

They use deprecate decorator for round function in core/series.py:1786-1808 I'm not sure what to do about that. Here's the code 

```    # ndarray compat
    argmin = deprecate(
        'argmin', idxmin, '0.21.0',
        msg=dedent("""\
        The current behaviour of 'Series.argmin' is deprecated, use 'idxmin'
        instead.
        The behavior of 'argmin' will be corrected to return the positional
        minimum in the future. For now, use 'series.values.argmin' or
        'np.argmin(np.array(values))' to get the position of the minimum
        row."""),
    )
    argmax = deprecate(
        'argmax', idxmax, '0.21.0',
        msg=dedent("""\
        The current behaviour of 'Series.argmax' is deprecated, use 'idxmax'
        instead.
        The behavior of 'argmax' will be corrected to return the positional
        maximum in the future. For now, use 'series.values.argmax' or
        'np.argmax(np.array(values))' to get the position of the maximum
        row.""")
    )

    def round(self, decimals=0, *args, **kwargs):
        """
        Round each value in a Series to the given number of decimals.

        Parameters
```

I forgot those were using the decorator, you can ignore them then, no problem.
Ok, Pull request covers everything except that issue

Commit message: Updated return message doc strings.

Patch to review:
diff --git a/pandas/core/arrays/sparse.py b/pandas/core/arrays/sparse.py
index 672261c2a407e..24e33c32d0898 100644
--- a/pandas/core/arrays/sparse.py
+++ b/pandas/core/arrays/sparse.py
@@ -1861,6 +1861,10 @@ def _make_index(length, indices, kind):
                               'sp_values'],
                 typ='property')
 class SparseAccessor(PandasDelegate):
+    """
+    Accessor for SparseSparse from other sparse matrix data types.
+    """
+
     def __init__(self, data=None):
         self._validate(data)
         # Store the Series since we need that for to_coo
diff --git a/pandas/core/base.py b/pandas/core/base.py
index de368f52b6f00..0c7bf9da8ff03 100644
--- a/pandas/core/base.py
+++ b/pandas/core/base.py
@@ -668,11 +668,13 @@ class IndexOpsMixin(object):
     __array_priority__ = 1000
 
     def transpose(self, *args, **kwargs):
-        """ return the transpose, which is by definition self """
+        """
+        Return the transpose, which is by definition self.
+        """
         nv.validate_transpose(args, kwargs)
         return self
 
-    T = property(transpose, doc="return the transpose, which is by "
+    T = property(transpose, doc="Return the transpose, which is by "
                                 "definition self")
 
     @property
@@ -692,19 +694,21 @@ def _is_homogeneous_type(self):
 
     @property
     def shape(self):
-        """ return a tuple of the shape of the underlying data """
+        """
+        Return a tuple of the shape of the underlying data.
+        """
         return self._values.shape
 
     @property
     def ndim(self):
-        """ return the number of dimensions of the underlying data,
-        by definition 1
+        """
+        Return the number of dimensions of the underlying data, by definition 1.
         """
         return 1
 
     def item(self):
-        """ return the first element of the underlying data as a python
-        scalar
+        """
+        Return the first element of the underlying data as a python scalar.
         """
         try:
             return self.values.item()
@@ -715,7 +719,9 @@ def item(self):
 
     @property
     def data(self):
-        """ return the data pointer of the underlying data """
+        """
+        Return the data pointer of the underlying data.
+        """
         warnings.warn("{obj}.data is deprecated and will be removed "
                       "in a future version".format(obj=type(self).__name__),
                       FutureWarning, stacklevel=2)
@@ -723,7 +729,9 @@ def data(self):
 
     @property
     def itemsize(self):
-        """ return the size of the dtype of the item of the underlying data """
+        """
+        Return the size of the dtype of the item of the underlying data.
+        """
         warnings.warn("{obj}.itemsize is deprecated and will be removed "
                       "in a future version".format(obj=type(self).__name__),
                       FutureWarning, stacklevel=2)
@@ -731,12 +739,16 @@ def itemsize(self):
 
     @property
     def nbytes(self):
-        """ return the number of bytes in the underlying data """
+        """
+        Return the number of bytes in the underlying data.
+        """
         return self._values.nbytes
 
     @property
     def strides(self):
-        """ return the strides of the underlying data """
+        """
+        Return the strides of the underlying data.
+        """
         warnings.warn("{obj}.strides is deprecated and will be removed "
                       "in a future version".format(obj=type(self).__name__),
                       FutureWarning, stacklevel=2)
@@ -744,12 +756,16 @@ def strides(self):
 
     @property
     def size(self):
-        """ return the number of elements in the underlying data """
+        """
+        Return the number of elements in the underlying data.
+        """
         return self._values.size
 
     @property
     def flags(self):
-        """ return the ndarray.flags for the underlying data """
+        """
+        Return the ndarray.flags for the underlying data
+        """
         warnings.warn("{obj}.flags is deprecated and will be removed "
                       "in a future version".format(obj=type(self).__name__),
                       FutureWarning, stacklevel=2)
@@ -757,8 +773,8 @@ def flags(self):
 
     @property
     def base(self):
-        """ return the base object if the memory of the underlying data is
-        shared
+        """
+        Return the base object if the memory of the underlying data is shared
         """
         warnings.warn("{obj}.base is deprecated and will be removed "
                       "in a future version".format(obj=type(self).__name__),
@@ -818,7 +834,7 @@ def max(self):
 
     def argmax(self, axis=None):
         """
-        return a ndarray of the maximum argument indexer
+        Return a ndarray of the maximum argument indexer.
 
         See also
         --------
@@ -861,7 +877,7 @@ def min(self):
 
     def argmin(self, axis=None):
         """
-        return a ndarray of the minimum argument indexer
+        Return a ndarray of the minimum argument indexer.
 
         See also
         --------
@@ -900,7 +916,9 @@ def __iter__(self):
 
     @cache_readonly
     def hasnans(self):
-        """ return if I have any nans; enables various perf speedups """
+        """
+        Return if I have any nans; enables various perf speedups.
+        """
         return bool(isna(self).any())
 
     def _reduce(self, op, name, axis=0, skipna=True, numeric_only=None,
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
index 34f25c5634d5b..9d98b534da37c 100644
--- a/pandas/core/generic.py
+++ b/pandas/core/generic.py
@@ -2328,7 +2328,7 @@ def to_hdf(self, path_or_buf, key, **kwargs):
 
     def to_msgpack(self, path_or_buf=None, encoding='utf-8', **kwargs):
         """
-        msgpack (serialize) object to input file path
+        Serialize object to input file path using msgpack format
 
         THIS IS AN EXPERIMENTAL LIBRARY and the storage format
         may not be stable until a future release.
diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py
index 1d9d3b1d3bd16..9f1e3def7acf9 100644
--- a/pandas/core/indexes/datetimelike.py
+++ b/pandas/core/indexes/datetimelike.py
@@ -80,7 +80,7 @@ class TimelikeOps(object):
 
     _round_doc = (
         """
-        {op} the data to the specified `freq`.
+        Perform {op} operation on the data to the specified `freq`.
 
         Parameters
         ----------
diff --git a/pandas/core/series.py b/pandas/core/series.py
index 20e4720a3bde7..47e0e97e4b810 100644
--- a/pandas/core/series.py
+++ b/pandas/core/series.py
@@ -118,7 +118,7 @@ class Series(base.IndexOpsMixin, generic.NDFrame):
     Parameters
     ----------
     data : array-like, Iterable, dict, or scalar value
-        Contains data stored in Series
+        Contains data stored in Series.
 
         .. versionchanged :: 0.23.0
            If data is a dict, argument order is maintained for Python 3.6
@@ -133,8 +133,8 @@ class Series(base.IndexOpsMixin, generic.NDFrame):
     dtype : str, numpy.dtype, or ExtensionDtype, optional
         dtype for the output Series. If not specified, this will be
         inferred from `data`.
-    copy : boolean, default False
-        Copy input data
+    copy : bool, default False
+        Copy input data.
     """
     _metadata = ['name']
     _accessors = {'dt', 'cat', 'str', 'sparse'}
@@ -390,22 +390,30 @@ def name(self, value):
     # ndarray compatibility
     @property
     def dtype(self):
-        """ return the dtype object of the underlying data """
+        """
+        Return the dtype object of the underlying data.
+        """
         return self._data.dtype
 
     @property
     def dtypes(self):
-        """ return the dtype object of the underlying data """
+        """
+        Return the dtype object of the underlying data.
+        """
         return self._data.dtype
 
     @property
     def ftype(self):
-        """ return if the data is sparse|dense """
+        """
+        Return if the data is sparse|dense.
+        """
         return self._data.ftype
 
     @property
     def ftypes(self):
-        """ return if the data is sparse|dense """
+        """
+        Return if the data is sparse|dense.
+        """
         return self._data.ftype
 
     @property
@@ -443,7 +451,9 @@ def values(self):
 
     @property
     def _values(self):
-        """ return the internal repr of this data """
+        """
+        Return the internal repr of this data.
+        """
         return self._data.internal_values()
 
     def _formatting_values(self):
@@ -453,7 +463,9 @@ def _formatting_values(self):
         return self._data.formatting_values()
 
     def get_values(self):
-        """ same as values (but handles sparseness conversions); is a view """
+        """
+        Same as values (but handles sparseness conversions); is a view.
+        """
         return self._data.get_values()
 
     @property
@@ -3453,9 +3465,9 @@ def rename(self, index=None, **kwargs):
             the index.
             Scalar or hashable sequence-like will alter the ``Series.name``
             attribute.
-        copy : boolean, default True
+        copy : bool, default True
             Also copy underlying data
-        inplace : boolean, default False
+        inplace : bool, default False
             Whether to return a new Series. If True then value of copy is
             ignored.
         level : int or level name, default None


Code review comments:
diff_hunk: @@ -715,50 +719,62 @@ def item(self):
 
     @property
     def data(self):
-        """ return the data pointer of the underlying data """
+        """
+        Return the data pointer of the underlying data.
+        """
         warnings.warn("{obj}.data is deprecated and will be removed "
                       "in a future version".format(obj=type(self).__name__),
                       FutureWarning, stacklevel=2)
         return self.values.data
 
     @property
     def itemsize(self):
-        """ return the size of the dtype of the item of the underlying data """
+        """
+        Return the size of the dtype of the item of the underlying data.
+        """
         warnings.warn("{obj}.itemsize is deprecated and will be removed "
                       "in a future version".format(obj=type(self).__name__),
                       FutureWarning, stacklevel=2)
         return self._ndarray_values.itemsize
 
     @property
     def nbytes(self):
-        """ return the number of bytes in the underlying data """
+        """
+        Return the number of bytes in the underlying data.
+        """
         return self._values.nbytes
 
     @property
     def strides(self):
-        """ return the strides of the underlying data """
+        """
+        Return the strides of the underlying data.
+        """
         warnings.warn("{obj}.strides is deprecated and will be removed "
                       "in a future version".format(obj=type(self).__name__),
                       FutureWarning, stacklevel=2)
         return self._ndarray_values.strides
 
     @property
     def size(self):
-        """ return the number of elements in the underlying data """
+        """
+        Return the number of elements in the underlying data.
+        """
         return self._values.size
 
     @property
     def flags(self):
-        """ return the ndarray.flags for the underlying data """
+        """
+        Return the ndarray.flags for the underlying data
+        """
         warnings.warn("{obj}.flags is deprecated and will be removed "
                       "in a future version".format(obj=type(self).__name__),
                       FutureWarning, stacklevel=2)
         return self.values.flags
 
     @property
     def base(self):
-        """ return the base object if the memory of the underlying data is
-        shared
+        """
+        Return the base object if the memory of the underlying data is shared
path: pandas/core/base.py
text: @user1:
```suggestion
        Return the base object if the memory of the underlying data is shared.
```