DOC: Improve reference/arrays.rst (pandas-dev#45189)

* DOC: Improve reference.arrays.rst

* Fix NaT docstrings

Author: mroeschke

doc/source/reference/arrays.rst

@@ -2,9 +2,9 @@
 
 .. _api.arrays:
 
-=============
-pandas arrays
-=============
+======================================
+pandas arrays, scalars, and data types
+======================================
 
 .. currentmodule:: pandas
 
@@ -141,11 +141,11 @@ Methods
    Timestamp.weekday
 
 A collection of timestamps may be stored in a :class:`arrays.DatetimeArray`.
-For timezone-aware data, the ``.dtype`` of a ``DatetimeArray`` is a
+For timezone-aware data, the ``.dtype`` of a :class:`arrays.DatetimeArray` is a
 :class:`DatetimeTZDtype`. For timezone-naive data, ``np.dtype("datetime64[ns]")``
 is used.
 
-If the data are tz-aware, then every value in the array must have the same timezone.
+If the data are timezone-aware, then every value in the array must have the same timezone.
 
 .. autosummary::
    :toctree: api/
@@ -206,7 +206,7 @@ Methods
    Timedelta.to_numpy
    Timedelta.total_seconds
 
-A collection of timedeltas may be stored in a :class:`TimedeltaArray`.
+A collection of :class:`Timedelta` may be stored in a :class:`TimedeltaArray`.
 
 .. autosummary::
    :toctree: api/
@@ -267,8 +267,8 @@ Methods
    Period.strftime
    Period.to_timestamp
 
-A collection of timedeltas may be stored in a :class:`arrays.PeriodArray`.
-Every period in a ``PeriodArray`` must have the same ``freq``.
+A collection of :class:`Period` may be stored in a :class:`arrays.PeriodArray`.
+Every period in a :class:`arrays.PeriodArray` must have the same ``freq``.
 
 .. autosummary::
    :toctree: api/
@@ -383,8 +383,8 @@ Categorical data
 ----------------
 
 pandas defines a custom data type for representing data that can take only a
-limited, fixed set of values. The dtype of a ``Categorical`` can be described by
-a :class:`pandas.api.types.CategoricalDtype`.
+limited, fixed set of values. The dtype of a :class:`Categorical` can be described by
+a :class:`CategoricalDtype`.
 
 .. autosummary::
    :toctree: api/
@@ -414,7 +414,7 @@ have the categories and integer codes already:
 
    Categorical.from_codes
 
-The dtype information is available on the ``Categorical``
+The dtype information is available on the :class:`Categorical`
 
 .. autosummary::
    :toctree: api/
@@ -425,21 +425,21 @@ The dtype information is available on the ``Categorical``
    Categorical.codes
 
 ``np.asarray(categorical)`` works by implementing the array interface. Be aware, that this converts
-the Categorical back to a NumPy array, so categories and order information is not preserved!
+the :class:`Categorical` back to a NumPy array, so categories and order information is not preserved!
 
 .. autosummary::
    :toctree: api/
 
    Categorical.__array__
 
-A ``Categorical`` can be stored in a ``Series`` or ``DataFrame``.
+A :class:`Categorical` can be stored in a :class:`Series` or :class:`DataFrame`.
 To create a Series of dtype ``category``, use ``cat = s.astype(dtype)`` or
 ``Series(..., dtype=dtype)`` where ``dtype`` is either
 
 * the string ``'category'``
-* an instance of :class:`~pandas.api.types.CategoricalDtype`.
+* an instance of :class:`CategoricalDtype`.
 
-If the Series is of dtype ``CategoricalDtype``, ``Series.cat`` can be used to change the categorical
+If the :class:`Series` is of dtype :class:`CategoricalDtype`, ``Series.cat`` can be used to change the categorical
 data. See :ref:`api.series.cat` for more.
 
 .. _api.arrays.sparse:
@@ -488,7 +488,7 @@ we recommend using :class:`StringDtype` (with the alias ``"string"``).
 
    StringDtype
 
-The ``Series.str`` accessor is available for ``Series`` backed by a :class:`arrays.StringArray`.
+The ``Series.str`` accessor is available for :class:`Series` backed by a :class:`arrays.StringArray`.
 See :ref:`api.series.str` for more.
 
 
@@ -498,7 +498,7 @@ Boolean data with missing values
 --------------------------------
 
 The boolean dtype (with the alias ``"boolean"``) provides support for storing
-boolean data (True, False values) with missing values, which is not possible
+boolean data (``True``, ``False``) with missing values, which is not possible
 with a bool :class:`numpy.ndarray`.
 
 .. autosummary::

pandas/_libs/tslibs/nattype.pyx

@@ -623,7 +623,7 @@ class NaTType(_NaT):
     astimezone = _make_error_func(
         "astimezone",
         """
-        Convert tz-aware Timestamp to another time zone.
+        Convert timezone-aware Timestamp to another time zone.
 
         Parameters
         ----------
@@ -1033,7 +1033,7 @@ timedelta}, default 'raise'
     tz_convert = _make_nat_func(
         "tz_convert",
         """
-        Convert tz-aware Timestamp to another time zone.
+        Convert timezone-aware Timestamp to another time zone.
 
         Parameters
         ----------
@@ -1078,7 +1078,7 @@ timedelta}, default 'raise'
         "tz_localize",
         """
         Convert naive Timestamp to local time zone, or remove
-        timezone from tz-aware Timestamp.
+        timezone from timezone-aware Timestamp.
 
         Parameters
         ----------

pandas/_libs/tslibs/period.pyx

@@ -1571,6 +1571,20 @@ cdef class PeriodMixin:
 
     @property
     def end_time(self) -> Timestamp:
+        """
+        Get the Timestamp for the end of the period.
+
+        Returns
+        -------
+        Timestamp
+
+        See Also
+        --------
+        Period.start_time : Return the start Timestamp.
+        Period.dayofyear : Return the day of year.
+        Period.daysinmonth : Return the days in that month.
+        Period.dayofweek : Return the day of the week.
+        """
         return self.to_timestamp(how="end")
 
     def _require_matching_freq(self, other, base=False):
@@ -1835,11 +1849,17 @@ cdef class _Period(PeriodMixin):
 
     @property
     def year(self) -> int:
+        """
+        Return the year this Period falls on.
+        """
         base = self._dtype._dtype_code
         return pyear(self.ordinal, base)
 
     @property
     def month(self) -> int:
+        """
+        Return the month this Period falls on.
+        """
         base = self._dtype._dtype_code
         return pmonth(self.ordinal, base)
 
@@ -1946,6 +1966,32 @@ cdef class _Period(PeriodMixin):
 
     @property
     def weekofyear(self) -> int:
+        """
+        Get the week of the year on the given Period.
+
+        Returns
+        -------
+        int
+
+        See Also
+        --------
+        Period.dayofweek : Get the day component of the Period.
+        Period.weekday : Get the day component of the Period.
+
+        Examples
+        --------
+        >>> p = pd.Period("2018-03-11", "H")
+        >>> p.weekofyear
+        10
+
+        >>> p = pd.Period("2018-02-01", "D")
+        >>> p.weekofyear
+        5
+
+        >>> p = pd.Period("2018-01-06", "D")
+        >>> p.weekofyear
+        1
+        """
         base = self._dtype._dtype_code
         return pweek(self.ordinal, base)
 
@@ -2120,6 +2166,9 @@ cdef class _Period(PeriodMixin):
 
     @property
     def quarter(self) -> int:
+        """
+        Return the quarter this Period falls on.
+        """
         base = self._dtype._dtype_code
         return pquarter(self.ordinal, base)
 
@@ -2225,14 +2274,23 @@ cdef class _Period(PeriodMixin):
 
     @property
     def is_leap_year(self) -> bool:
+        """
+        Return True if the period's year is in a leap year.
+        """
         return bool(is_leapyear(self.year))
 
     @classmethod
     def now(cls, freq=None):
+        """
+        Return the period of now's date.
+        """
         return Period(datetime.now(), freq=freq)
 
     @property
     def freqstr(self) -> str:
+        """
+        Return a string representation of the frequency.
+        """
         return self.freq.freqstr
 
     def __repr__(self) -> str:

pandas/_libs/tslibs/timedeltas.pyx

@@ -886,7 +886,7 @@ cdef class _Timedelta(timedelta):
 
     cpdef timedelta to_pytimedelta(_Timedelta self):
         """
-        Convert a pandas Timedelta object into a python timedelta object.
+        Convert a pandas Timedelta object into a python ``datetime.timedelta`` object.
 
         Timedelta objects are internally saved as numpy datetime64[ns] dtype.
         Use to_pytimedelta() to convert to object dtype.

pandas/_libs/tslibs/timestamps.pyx

@@ -740,7 +740,7 @@ cdef class _Timestamp(ABCTimestamp):
 
     def isoformat(self, sep: str = "T", timespec: str = "auto") -> str:
         """
-        Return the time formatted according to ISO.
+        Return the time formatted according to ISO 8610.
 
         The full format looks like 'YYYY-MM-DD HH:MM:SS.mmmmmmnnn'.
         By default, the fractional part is omitted if self.microsecond == 0
@@ -1749,7 +1749,7 @@ timedelta}, default 'raise'
     def tz_localize(self, tz, ambiguous='raise', nonexistent='raise'):
         """
         Convert naive Timestamp to local time zone, or remove
-        timezone from tz-aware Timestamp.
+        timezone from timezone-aware Timestamp.
 
         Parameters
         ----------
@@ -1852,7 +1852,7 @@ default 'raise'
 
     def tz_convert(self, tz):
         """
-        Convert tz-aware Timestamp to another time zone.
+        Convert timezone-aware Timestamp to another time zone.
 
         Parameters
         ----------