DOC: fix docstring for DataFrame.to_period, pandas.DataFrame.to_timestamp, pandas.DataFrame.tz_convert #58065 (#58101)

* Add See Also section to to_period method.

* Add See Also section to to_timestamp method.

* Add See Also section to tz_convert method.

* fix typo in to_timestamp

* Fix formatting of See Also

* Remove fixed methods from code check ignore list.

* Fix formatting

* Revert accidentally included docstring changes.

* fix merge issues

* Fix pre commit hooks

* Fix line break issues.

Author: bergnerjonas

ci/code_checks.sh

@@ -120,9 +120,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.DataFrame.to_feather SA01" \
         -i "pandas.DataFrame.to_markdown SA01" \
         -i "pandas.DataFrame.to_parquet RT03" \
-        -i "pandas.DataFrame.to_period SA01" \
-        -i "pandas.DataFrame.to_timestamp SA01" \
-        -i "pandas.DataFrame.tz_convert SA01" \
         -i "pandas.DataFrame.var PR01,RT03,SA01" \
         -i "pandas.DatetimeIndex.ceil SA01" \
         -i "pandas.DatetimeIndex.date SA01" \
@@ -467,11 +464,8 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Series.to_frame SA01" \
         -i "pandas.Series.to_list RT03" \
         -i "pandas.Series.to_markdown SA01" \
-        -i "pandas.Series.to_period SA01" \
         -i "pandas.Series.to_string SA01" \
-        -i "pandas.Series.to_timestamp RT03,SA01" \
         -i "pandas.Series.truediv PR07" \
-        -i "pandas.Series.tz_convert SA01" \
         -i "pandas.Series.update PR07,SA01" \
         -i "pandas.Series.var PR01,RT03,SA01" \
         -i "pandas.SparseDtype SA01" \

pandas/core/frame.py

@@ -12482,7 +12482,9 @@ def to_timestamp(
         copy: bool | lib.NoDefault = lib.no_default,
     ) -> DataFrame:
         """
-        Cast to DatetimeIndex of timestamps, at *beginning* of period.
+        Cast PeriodIndex to DatetimeIndex of timestamps, at *beginning* of period.
+
+        This can be changed to the *end* of the period, by specifying `how="e"`.
 
         Parameters
         ----------
@@ -12512,8 +12514,13 @@ def to_timestamp(
 
         Returns
         -------
-        DataFrame
-            The DataFrame has a DatetimeIndex.
+        DataFrame with DatetimeIndex
+            DataFrame with the PeriodIndex cast to DatetimeIndex.
+
+        See Also
+        --------
+        DataFrame.to_period: Inverse method to cast DatetimeIndex to PeriodIndex.
+        Series.to_timestamp: Equivalent method for Series.
 
         Examples
         --------
@@ -12569,7 +12576,8 @@ def to_period(
         Convert DataFrame from DatetimeIndex to PeriodIndex.
 
         Convert DataFrame from DatetimeIndex to PeriodIndex with desired
-        frequency (inferred from index if not passed).
+        frequency (inferred from index if not passed). Either index of columns can be
+        converted, depending on `axis` argument.
 
         Parameters
         ----------
@@ -12597,7 +12605,12 @@ def to_period(
         Returns
         -------
         DataFrame
-            The DataFrame has a PeriodIndex.
+            The DataFrame with the converted PeriodIndex.
+
+        See Also
+        --------
+        Series.to_period: Equivalent method for Series.
+        Series.dt.to_period: Convert DateTime column values.
 
         Examples
         --------

pandas/core/generic.py

@@ -10394,6 +10394,11 @@ def tz_convert(
         TypeError
             If the axis is tz-naive.
 
+        See Also
+        --------
+        DataFrame.tz_localize: Localize tz-naive index of DataFrame to target time zone.
+        Series.tz_localize: Localize tz-naive index of Series to target time zone.
+
         Examples
         --------
         Change to another time zone:

pandas/core/series.py

@@ -5613,6 +5613,8 @@ def to_timestamp(
         """
         Cast to DatetimeIndex of Timestamps, at *beginning* of period.
 
+        This can be changed to the *end* of the period, by specifying `how="e"`.
+
         Parameters
         ----------
         freq : str, default frequency of PeriodIndex
@@ -5640,6 +5642,12 @@ def to_timestamp(
         Returns
         -------
         Series with DatetimeIndex
+            Series with the PeriodIndex cast to DatetimeIndex.
+
+        See Also
+        --------
+        Series.to_period: Inverse method to cast DatetimeIndex to PeriodIndex.
+        DataFrame.to_timestamp: Equivalent method for DataFrame.
 
         Examples
         --------
@@ -5713,6 +5721,11 @@ def to_period(
         Series
             Series with index converted to PeriodIndex.
 
+        See Also
+        --------
+        DataFrame.to_period: Equivalent method for DataFrame.
+        Series.dt.to_period: Convert DateTime column values.
+
         Examples
         --------
         >>> idx = pd.DatetimeIndex(["2023", "2024", "2025"])