DOC: fix docstring validation errors for pandas.PeriodIndex (#59638)

* DOC: pandas.PeriodIndex GL08, PR07, RT03, and SA01 docstring validation errors fixed

* DOC: pandas.Series.dt.qyear docstring validation error addressed by existing series.PeriodIndex.qyear docstring validation fix

Author: hlakams

ci/code_checks.sh

@@ -81,27 +81,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Period.to_timestamp SA01" \
         -i "pandas.PeriodDtype SA01" \
         -i "pandas.PeriodDtype.freq SA01" \
-        -i "pandas.PeriodIndex.day SA01" \
-        -i "pandas.PeriodIndex.day_of_week SA01" \
-        -i "pandas.PeriodIndex.day_of_year SA01" \
-        -i "pandas.PeriodIndex.dayofweek SA01" \
-        -i "pandas.PeriodIndex.dayofyear SA01" \
-        -i "pandas.PeriodIndex.days_in_month SA01" \
-        -i "pandas.PeriodIndex.daysinmonth SA01" \
-        -i "pandas.PeriodIndex.from_fields PR07,SA01" \
-        -i "pandas.PeriodIndex.from_ordinals SA01" \
-        -i "pandas.PeriodIndex.hour SA01" \
-        -i "pandas.PeriodIndex.is_leap_year SA01" \
-        -i "pandas.PeriodIndex.minute SA01" \
-        -i "pandas.PeriodIndex.month SA01" \
-        -i "pandas.PeriodIndex.quarter SA01" \
-        -i "pandas.PeriodIndex.qyear GL08" \
-        -i "pandas.PeriodIndex.second SA01" \
-        -i "pandas.PeriodIndex.to_timestamp RT03,SA01" \
-        -i "pandas.PeriodIndex.week SA01" \
-        -i "pandas.PeriodIndex.weekday SA01" \
-        -i "pandas.PeriodIndex.weekofyear SA01" \
-        -i "pandas.PeriodIndex.year SA01" \
         -i "pandas.RangeIndex PR07" \
         -i "pandas.RangeIndex.from_range PR01,SA01" \
         -i "pandas.RangeIndex.start SA01" \
@@ -124,7 +103,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Series.dt.month_name PR01,PR02" \
         -i "pandas.Series.dt.nanoseconds SA01" \
         -i "pandas.Series.dt.normalize PR01" \
-        -i "pandas.Series.dt.qyear GL08" \
         -i "pandas.Series.dt.round PR01,PR02" \
         -i "pandas.Series.dt.seconds SA01" \
         -i "pandas.Series.dt.strftime PR01,PR02" \

pandas/core/arrays/period.py

@@ -432,6 +432,15 @@ def __arrow_array__(self, type=None):
         """
         The year of the period.
 
+        See Also
+        --------
+        PeriodIndex.day_of_year : The ordinal day of the year.
+        PeriodIndex.dayofyear : The ordinal day of the year.
+        PeriodIndex.is_leap_year : Logical indicating if the date belongs to a
+            leap year.
+        PeriodIndex.weekofyear : The week ordinal of the year.
+        PeriodIndex.year : The year of the period.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y")
@@ -444,6 +453,11 @@ def __arrow_array__(self, type=None):
         """
         The month as January=1, December=12.
 
+        See Also
+        --------
+        PeriodIndex.days_in_month : The number of days in the month.
+        PeriodIndex.daysinmonth : The number of days in the month.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
@@ -456,6 +470,16 @@ def __arrow_array__(self, type=None):
         """
         The days of the period.
 
+        See Also
+        --------
+        PeriodIndex.day_of_week : The day of the week with Monday=0, Sunday=6.
+        PeriodIndex.day_of_year : The ordinal day of the year.
+        PeriodIndex.dayofweek : The day of the week with Monday=0, Sunday=6.
+        PeriodIndex.dayofyear : The ordinal day of the year.
+        PeriodIndex.days_in_month : The number of days in the month.
+        PeriodIndex.daysinmonth : The number of days in the month.
+        PeriodIndex.weekday : The day of the week with Monday=0, Sunday=6.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex(['2020-01-31', '2020-02-28'], freq='D')
@@ -468,6 +492,12 @@ def __arrow_array__(self, type=None):
         """
         The hour of the period.
 
+        See Also
+        --------
+        PeriodIndex.minute : The minute of the period.
+        PeriodIndex.second : The second of the period.
+        PeriodIndex.to_timestamp : Cast to DatetimeArray/Index.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex(["2023-01-01 10:00", "2023-01-01 11:00"], freq='h')
@@ -480,6 +510,12 @@ def __arrow_array__(self, type=None):
         """
         The minute of the period.
 
+        See Also
+        --------
+        PeriodIndex.hour : The hour of the period.
+        PeriodIndex.second : The second of the period.
+        PeriodIndex.to_timestamp : Cast to DatetimeArray/Index.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex(["2023-01-01 10:30:00",
@@ -493,6 +529,12 @@ def __arrow_array__(self, type=None):
         """
         The second of the period.
 
+        See Also
+        --------
+        PeriodIndex.hour : The hour of the period.
+        PeriodIndex.minute : The minute of the period.
+        PeriodIndex.to_timestamp : Cast to DatetimeArray/Index.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex(["2023-01-01 10:00:30",
@@ -506,6 +548,14 @@ def __arrow_array__(self, type=None):
         """
         The week ordinal of the year.
 
+        See Also
+        --------
+        PeriodIndex.day_of_week : The day of the week with Monday=0, Sunday=6.
+        PeriodIndex.dayofweek : The day of the week with Monday=0, Sunday=6.
+        PeriodIndex.week : The week ordinal of the year.
+        PeriodIndex.weekday : The day of the week with Monday=0, Sunday=6.
+        PeriodIndex.year : The year of the period.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
@@ -519,6 +569,17 @@ def __arrow_array__(self, type=None):
         """
         The day of the week with Monday=0, Sunday=6.
 
+        See Also
+        --------
+        PeriodIndex.day : The days of the period.
+        PeriodIndex.day_of_week : The day of the week with Monday=0, Sunday=6.
+        PeriodIndex.day_of_year : The ordinal day of the year.
+        PeriodIndex.dayofweek : The day of the week with Monday=0, Sunday=6.
+        PeriodIndex.dayofyear : The ordinal day of the year.
+        PeriodIndex.week : The week ordinal of the year.
+        PeriodIndex.weekday : The day of the week with Monday=0, Sunday=6.
+        PeriodIndex.weekofyear : The week ordinal of the year.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex(["2023-01-01", "2023-01-02", "2023-01-03"], freq="D")
@@ -533,6 +594,17 @@ def __arrow_array__(self, type=None):
         """
         The ordinal day of the year.
 
+        See Also
+        --------
+        PeriodIndex.day : The days of the period.
+        PeriodIndex.day_of_week : The day of the week with Monday=0, Sunday=6.
+        PeriodIndex.day_of_year : The ordinal day of the year.
+        PeriodIndex.dayofweek : The day of the week with Monday=0, Sunday=6.
+        PeriodIndex.dayofyear : The ordinal day of the year.
+        PeriodIndex.weekday : The day of the week with Monday=0, Sunday=6.
+        PeriodIndex.weekofyear : The week ordinal of the year.
+        PeriodIndex.year : The year of the period.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex(["2023-01-10", "2023-02-01", "2023-03-01"], freq="D")
@@ -551,19 +623,74 @@ def __arrow_array__(self, type=None):
         """
         The quarter of the date.
 
+        See Also
+        --------
+        PeriodIndex.qyear : Fiscal year the Period lies in according to its
+            starting-quarter.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
         >>> idx.quarter
         Index([1, 1, 1], dtype='int64')
         """,
     )
-    qyear = _field_accessor("qyear")
+    qyear = _field_accessor(
+        "qyear",
+        """
+        Fiscal year the Period lies in according to its starting-quarter.
+
+        The `year` and the `qyear` of the period will be the same if the fiscal
+        and calendar years are the same. When they are not, the fiscal year
+        can be different from the calendar year of the period.
+
+        Returns
+        -------
+        int
+            The fiscal year of the period.
+
+        See Also
+        --------
+        PeriodIndex.quarter : The quarter of the date.
+        PeriodIndex.year : The year of the period.
+
+        Examples
+        --------
+        If the natural and fiscal year are the same, `qyear` and `year` will
+        be the same.
+
+        >>> per = pd.Period('2018Q1', freq='Q')
+        >>> per.qyear
+        2018
+        >>> per.year
+        2018
+
+        If the fiscal year starts in April (`Q-MAR`), the first quarter of
+        2018 will start in April 2017. `year` will then be 2017, but `qyear`
+        will be the fiscal year, 2018.
+
+        >>> per = pd.Period('2018Q1', freq='Q-MAR')
+        >>> per.start_time
+        Timestamp('2017-04-01 00:00:00')
+        >>> per.qyear
+        2018
+        >>> per.year
+        2017
+        """,
+    )
+
     days_in_month = _field_accessor(
         "days_in_month",
         """
         The number of days in the month.
 
+        See Also
+        --------
+        PeriodIndex.day : The days of the period.
+        PeriodIndex.days_in_month : The number of days in the month.
+        PeriodIndex.daysinmonth : The number of days in the month.
+        PeriodIndex.month : The month as January=1, December=12.
+
         Examples
         --------
         For Series:
@@ -595,6 +722,12 @@ def is_leap_year(self) -> npt.NDArray[np.bool_]:
         """
         Logical indicating if the date belongs to a leap year.
 
+        See Also
+        --------
+        PeriodIndex.qyear : Fiscal year the Period lies in according to its
+            starting-quarter.
+        PeriodIndex.year : The year of the period.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y")
@@ -618,6 +751,19 @@ def to_timestamp(self, freq=None, how: str = "start") -> DatetimeArray:
         Returns
         -------
         DatetimeArray/Index
+            Timestamp representation of given Period-like object.
+
+        See Also
+        --------
+        PeriodIndex.day : The days of the period.
+        PeriodIndex.from_fields : Construct a PeriodIndex from fields
+            (year, month, day, etc.).
+        PeriodIndex.from_ordinals : Construct a PeriodIndex from ordinals.
+        PeriodIndex.hour : The hour of the period.
+        PeriodIndex.minute : The minute of the period.
+        PeriodIndex.month : The month as January=1, December=12.
+        PeriodIndex.second : The second of the period.
+        PeriodIndex.year : The year of the period.
 
         Examples
         --------

pandas/core/indexes/period.py

@@ -261,19 +261,31 @@ def from_fields(
         Parameters
         ----------
         year : int, array, or Series, default None
+            Year for the PeriodIndex.
         quarter : int, array, or Series, default None
+            Quarter for the PeriodIndex.
         month : int, array, or Series, default None
+            Month for the PeriodIndex.
         day : int, array, or Series, default None
+            Day for the PeriodIndex.
         hour : int, array, or Series, default None
+            Hour for the PeriodIndex.
         minute : int, array, or Series, default None
+            Minute for the PeriodIndex.
         second : int, array, or Series, default None
+            Second for the PeriodIndex.
         freq : str or period object, optional
             One of pandas period strings or corresponding objects.
 
         Returns
         -------
         PeriodIndex
 
+        See Also
+        --------
+        PeriodIndex.from_ordinals : Construct a PeriodIndex from ordinals.
+        PeriodIndex.to_timestamp : Cast to DatetimeArray/Index.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex.from_fields(year=[2000, 2002], quarter=[1, 3])
@@ -311,6 +323,12 @@ def from_ordinals(cls, ordinals, *, freq, name=None) -> Self:
         -------
         PeriodIndex
 
+        See Also
+        --------
+        PeriodIndex.from_fields : Construct a PeriodIndex from fields
+            (year, month, day, etc.).
+        PeriodIndex.to_timestamp : Cast to DatetimeArray/Index.
+
         Examples
         --------
         >>> idx = pd.PeriodIndex.from_ordinals([-1, 0, 1], freq="Q")