DOC: update the pandas.Series.str.rpartition() docstring (Delhi)

pandas/core/strings.py

@@ -2340,47 +2340,82 @@ def rsplit(self, pat=None, n=-1, expand=False):
         return self._wrap_result(result, expand=expand)
 
     _shared_docs['str_partition'] = ("""
-    Split the string at the %(side)s occurrence of `sep`, and return 3 elements
-    containing the part before the separator, the separator itself,
-    and the part after the separator.
+    Split the string at the %(side)s occurrence of `sep`.
+
+    This method splits the string at the %(side)s occurrence of `sep`,
+    and returns 3 elements containing the part before the separator,
+    the separator itself, and the part after the separator.
     If the separator is not found, return %(return)s.
 
     Parameters
     ----------
-    pat : string, default whitespace
+    pat : str, default whitespace
         String to split on.
     expand : bool, default True
-        * If True, return DataFrame/MultiIndex expanding dimensionality.
-        * If False, return Series/Index.
+        If True, return DataFrame/MultiIndex expanding dimensionality.
+        If False, return Series/Index.
 
     Returns
     -------
-    split : DataFrame/MultiIndex or Series/Index of objects
+    DataFrame/MultiIndex or Series/Index of objects
 
     See Also
     --------
     %(also)s
+    Series.str.split : Split strings around given separators.
+    str.partition : Standard library version.
 
     Examples
     --------
 
-    >>> s = Series(['A_B_C', 'D_E_F', 'X'])
-    0    A_B_C
-    1    D_E_F
-    2        X
+    >>> s = pd.Series(['Linda van der Berg', 'George Pitt-Rivers'])
+    >>> s
+    0    Linda van der Berg
+    1    George Pitt-Rivers
     dtype: object
 
-    >>> s.str.partition('_')
-       0  1    2
-    0  A  _  B_C
-    1  D  _  E_F
-    2  X
-
-    >>> s.str.rpartition('_')
-         0  1  2
-    0  A_B  _  C
-    1  D_E  _  F
-    2          X
+    >>> s.str.partition()
+            0  1             2
+    0   Linda     van der Berg
+    1  George      Pitt-Rivers
+
+    To partition by the last space instead of the first one:
+
+    >>> s.str.rpartition()
+                   0  1            2
+    0  Linda van der            Berg
+    1         George     Pitt-Rivers
+
+    To partition by something different than a space:
+
+    >>> s.str.partition('-')
+                        0  1       2
+    0  Linda van der Berg
+    1         George Pitt  -  Rivers
+
+    To return a Series containining tuples instead of a DataFrame:
+
+    >>> s.str.partition('-', expand=False)
+    0    (Linda van der Berg, , )
+    1    (George Pitt, -, Rivers)
+    dtype: object
+
+    Also available on indices:
+
+    >>> idx = pd.Index(['X 123', 'Y 999'])
+    >>> idx
+    Index(['X 123', 'Y 999'], dtype='object')
+
+    Which will create a MultiIndex:
+
+    >>> idx.str.partition()
+    MultiIndex(levels=[['X', 'Y'], [' '], ['123', '999']],
+               labels=[[0, 1], [0, 0], [0, 1]])
+
+    Or an index with tuples with ``expand=False``:
+
+    >>> idx.str.partition(expand=False)
+    Index([('X', ' ', '123'), ('Y', ' ', '999')], dtype='object')
     """)
 
     @Appender(_shared_docs['str_partition'] % {