Add nsorted to series API docs and add docstring

Author: MartinBraquet

doc/source/reference/series.rst

@@ -152,8 +152,6 @@ Computations / descriptive stats
    Series.median
    Series.min
    Series.mode
-   Series.nlargest
-   Series.nsmallest
    Series.pct_change
    Series.prod
    Series.quantile
@@ -228,6 +226,9 @@ Reshaping, sorting
    Series.argmin
    Series.argmax
    Series.reorder_levels
+   Series.nlargest
+   Series.nsmallest
+   Series.nsorted
    Series.sort_values
    Series.sort_index
    Series.swaplevel

pandas/core/series.py

@@ -3840,6 +3840,81 @@ def nsorted(
         ascending: bool,
         keep: NsmallestNlargestKeep = "first",
     ) -> Series:
+        """
+        Return the top `n` elements, sorted in ascending or descending order.
+
+        Parameters
+        ----------
+        n : int, default 5
+            Return this many descending sorted values.
+        ascending : bool
+            If True, return the smallest `n` elements. If False, return
+            largest `n` elements.
+        keep : {'first', 'last', 'all'}, default 'first'
+            When there are duplicate values that cannot all fit in a
+            Series of `n` elements:
+
+            - ``first`` : return the first `n` occurrences in order
+              of appearance.
+            - ``last`` : return the last `n` occurrences in reverse
+              order of appearance.
+            - ``all`` : keep all occurrences. This can result in a Series of
+              size larger than `n`.
+
+        Returns
+        -------
+        Series
+            The `n` top values in the Series.
+
+        See Also
+        --------
+        Series.nsmallest: Get the `n` smallest elements.
+        Series.nlargest: Get the `n` largest elements.
+
+        Examples
+        --------
+        >>> countries_population = {
+        ...     "Italy": 59000000,
+        ...     "France": 65000000,
+        ...     "Malta": 434000,
+        ...     "Maldives": 434000,
+        ...     "Brunei": 434000,
+        ...     "Iceland": 337000,
+        ...     "Nauru": 11300,
+        ...     "Tuvalu": 11300,
+        ...     "Anguilla": 11300,
+        ...     "Montserrat": 5200,
+        ... }
+        >>> s = pd.Series(countries_population)
+        >>> s
+        Italy       59000000
+        France      65000000
+        Malta         434000
+        Maldives      434000
+        Brunei        434000
+        Iceland       337000
+        Nauru          11300
+        Tuvalu         11300
+        Anguilla       11300
+        Montserrat      5200
+        dtype: int64
+
+        Get the `n` largest elements.
+
+        >>> s.nsorted(n=3, ascending=False)
+        France      65000000
+        Italy       59000000
+        Malta         434000
+        dtype: int64
+
+        Get the `n` smallest elements.
+
+        >>> s.nsorted(n=3, ascending=True)
+        Montserrat     5200
+        Nauru         11300
+        Tuvalu        11300
+        dtype: int64
+        """
         return selectn.SelectNSeries(
             self,
             n=n,