chore: update docstring for astype (#485)

* chore: update docstring for astype

* minor fix

* minor fixes to pass doc test

Author: junyazhang

third_party/bigframes_vendored/pandas/core/generic.py

@@ -123,28 +123,55 @@ def astype(self, dtype):
 
         Create a series of type ``Int64``:
 
-            >>> ser = bpd.Series([1, 2], dtype='Int64')
+            >>> ser = bpd.Series([2023010000246789, 1624123244123101, 1054834234120101], dtype='Int64')
             >>> ser
-            0    1
-            1    2
+            0    2023010000246789
+            1    1624123244123101
+            2    1054834234120101
             dtype: Int64
 
         Convert to ``Float64`` type:
 
             >>> ser.astype('Float64')
-            0    1.0
-            1    2.0
+            0    2023010000246789.0
+            1    1624123244123101.0
+            2    1054834234120101.0
             dtype: Float64
 
+        Convert to ``pd.ArrowDtype(pa.timestamp("us", tz="UTC"))`` type:
+
+            >>> ser.astype("timestamp[us, tz=UTC][pyarrow]")
+            0    2034-02-08 11:13:20.246789+00:00
+            1    2021-06-19 17:20:44.123101+00:00
+            2    2003-06-05 17:30:34.120101+00:00
+            dtype: timestamp[us, tz=UTC][pyarrow]
+
+        Note that this is equivalent of using ``to_datetime`` with ``unit='us'``:
+
+            >>> bpd.to_datetime(ser, unit='us', utc=True)
+            0    2034-02-08 11:13:20.246789+00:00
+            1    2021-06-19 17:20:44.123101+00:00
+            2    2003-06-05 17:30:34.120101+00:00
+            dtype: timestamp[us, tz=UTC][pyarrow]
+
+        Convert ``pd.ArrowDtype(pa.timestamp("us", tz="UTC"))`` type to ``Int64`` type:
+
+            >>> timestamp_ser = ser.astype("timestamp[us, tz=UTC][pyarrow]")
+            >>> timestamp_ser.astype('Int64')
+            0    2023010000246789
+            1    1624123244123101
+            2    1054834234120101
+            dtype: Int64
+
         Args:
             dtype (str or pandas.ExtensionDtype):
-                A dtype supported by BigQuery DataFrame include 'boolean','Float64','Int64',
-                'string', 'string[pyarrow]','timestamp[us, tz=UTC][pyarrow]',
-                'timestamp[us][pyarrow]','date32[day][pyarrow]','time64[us][pyarrow]'
-                A pandas.ExtensionDtype include pandas.BooleanDtype(), pandas.Float64Dtype(),
-                pandas.Int64Dtype(), pandas.StringDtype(storage="pyarrow"),
-                pd.ArrowDtype(pa.date32()), pd.ArrowDtype(pa.time64("us")),
-                pd.ArrowDtype(pa.timestamp("us")), pd.ArrowDtype(pa.timestamp("us", tz="UTC")).
+                A dtype supported by BigQuery DataFrame include ``'boolean'``, ``'Float64'``, ``'Int64'``,
+                ``'int64[pyarrow]'``, ``'string'``, ``'string[pyarrow]'``, ``'timestamp[us, tz=UTC][pyarrow]'``,
+                ``'timestamp\[us\]\[pyarrow\]'``, ``'date32\[day\]\[pyarrow\]'``, ``'time64\[us\]\[pyarrow\]'``.
+                A pandas.ExtensionDtype include ``pandas.BooleanDtype()``, ``pandas.Float64Dtype()``,
+                ``pandas.Int64Dtype()``, ``pandas.StringDtype(storage="pyarrow")``,
+                ``pd.ArrowDtype(pa.date32())``, ``pd.ArrowDtype(pa.time64("us"))``,
+                ``pd.ArrowDtype(pa.timestamp("us"))``, ``pd.ArrowDtype(pa.timestamp("us", tz="UTC"))``.
 
         Returns:
             same type as caller