DOC: fix GL08 for pandas.tseries.offsets.YearEnd.rule_code

ci/code_checks.sh

@@ -451,15 +451,13 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.tseries.offsets.BYearBegin.n GL08" \
         -i "pandas.tseries.offsets.BYearBegin.nanos GL08" \
         -i "pandas.tseries.offsets.BYearBegin.normalize GL08" \
-        -i "pandas.tseries.offsets.BYearBegin.rule_code GL08" \
         -i "pandas.tseries.offsets.BYearEnd PR02" \
         -i "pandas.tseries.offsets.BYearEnd.freqstr SA01" \
         -i "pandas.tseries.offsets.BYearEnd.is_on_offset GL08" \
         -i "pandas.tseries.offsets.BYearEnd.month GL08" \
         -i "pandas.tseries.offsets.BYearEnd.n GL08" \
         -i "pandas.tseries.offsets.BYearEnd.nanos GL08" \
         -i "pandas.tseries.offsets.BYearEnd.normalize GL08" \
-        -i "pandas.tseries.offsets.BYearEnd.rule_code GL08" \
         -i "pandas.tseries.offsets.BusinessDay PR02,SA01" \
         -i "pandas.tseries.offsets.BusinessDay.calendar GL08" \
         -i "pandas.tseries.offsets.BusinessDay.freqstr SA01" \
@@ -712,14 +710,12 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.tseries.offsets.YearBegin.n GL08" \
         -i "pandas.tseries.offsets.YearBegin.nanos GL08" \
         -i "pandas.tseries.offsets.YearBegin.normalize GL08" \
-        -i "pandas.tseries.offsets.YearBegin.rule_code GL08" \
         -i "pandas.tseries.offsets.YearEnd.freqstr SA01" \
         -i "pandas.tseries.offsets.YearEnd.is_on_offset GL08" \
         -i "pandas.tseries.offsets.YearEnd.month GL08" \
         -i "pandas.tseries.offsets.YearEnd.n GL08" \
         -i "pandas.tseries.offsets.YearEnd.nanos GL08" \
         -i "pandas.tseries.offsets.YearEnd.normalize GL08" \
-        -i "pandas.tseries.offsets.YearEnd.rule_code GL08" \
         -i "pandas.util.hash_pandas_object PR07,SA01" # There should be no backslash in the final line, please keep this comment in the last ignored function
 
     RET=$(($RET + $?)) ; echo $MSG "DONE"

pandas/_libs/tslibs/offsets.pyx

@@ -2466,6 +2466,68 @@ cdef class YearOffset(SingleConstructorOffset):
 
     @property
     def rule_code(self) -> str:
+        """
+        Return the rule code for the YearEnd offset.
+
+        The `rule_code` is a shorthand identifier used within pandas to denote
+        the end-of-year frequency. This code is useful when working with time
+        series data, particularly when you need to perform operations that require
+        a specific frequency. For example, it can be used in functions like
+        `pd.date_range`, `resample`, or `asfreq` to indicate that operations
+        should be aligned to the end of the year. The YearEnd offset represents the
+        end of a year, typically on December 31st. The `rule_code` for this offset
+        helps to abstract away the complexity of manually calculating end-of-year
+        dates, especially when handling irregular date ranges or resampling data.
+
+        Returns
+        -------
+        str
+            The rule code associated with the YearEnd offset.
+
+        See Also
+        --------
+        date_range : Generate a range of dates with a specific frequency.
+        Series.resample : Resample time-series data.
+        tseries.offsets.Week : Represents a weekly offset.
+        DateOffset : Base class for all other offset classes.
+        tseries.offsets.Day : Represents a single day offset.
+        tseries.offsets.MonthEnd : Represents a monthly offset that
+            snaps to the end of the month.
+
+        Examples
+        --------
+        Create a date range with random dates
+        >>> date_range = pd.to_datetime([
+        ...     '2020-01-01', '2020-07-15', '2021-02-28', '2021-08-20', '2022-03-10'
+        ... ])
+        Create a DataFrame with the date_range as index and some random data
+        >>> data = np.random.rand(len(date_range))
+        >>> df = pd.DataFrame(data, index=date_range, columns=['Value'])
+        Print the original DataFrame
+        >>> df
+                       Value
+        2020-01-01  0.460402
+        2020-07-15  0.339131
+        2021-02-28  0.697027
+        2021-08-20  0.839201
+        2022-03-10  0.079523
+
+        Use the YearEnd.offsets with its rule_code
+        >>> year_end = pd.tseries.offsets.YearEnd()
+        >>> rule_code = year_end.rule_code
+        >>> rule_code
+        YE-DEC
+
+        Resample the data using the YearEnd rule code
+        >>> df_resampled = df.resample(rule_code).sum()
+
+        Print the resampled DataFrame
+        >>df_resampled
+                       Value
+        2020-12-31  0.799533
+        2021-12-31  1.536228
+        2022-12-31  0.079523
+        """
         month = MONTH_ALIASES[self.month]
         return f"{self._prefix}-{month}"