DOC: Enforce Numpy Docstring Validation for pandas.Index.join (pandas-dev#58560)

* DOC: add PR07,RT03,SA01 for pandas.Index.join

* DOC: remove PR07,RT03,SA01 for pandas.Index.join

* DOC: add PR07,RT03,SA01 for pandas.Index.join

* DOC: fix example output

Author: tuhinsharma121

ci/code_checks.sh

@@ -79,7 +79,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.DataFrame.swaplevel SA01" \
         -i "pandas.Grouper PR02" \
         -i "pandas.Index PR07" \
-        -i "pandas.Index.join PR07,RT03,SA01" \
         -i "pandas.Index.ravel PR01,RT03" \
         -i "pandas.Interval PR02" \
         -i "pandas.IntervalIndex.closed SA01" \

pandas/core/indexes/base.py

@@ -4316,23 +4316,37 @@ def join(
         Parameters
         ----------
         other : Index
+            The other index on which join is performed.
         how : {'left', 'right', 'inner', 'outer'}
         level : int or level name, default None
+            It is either the integer position or the name of the level.
         return_indexers : bool, default False
+            Whether to return the indexers or not for both the index objects.
         sort : bool, default False
             Sort the join keys lexicographically in the result Index. If False,
             the order of the join keys depends on the join type (how keyword).
 
         Returns
         -------
         join_index, (left_indexer, right_indexer)
+            The new index.
+
+        See Also
+        --------
+        DataFrame.join : Join columns with `other` DataFrame either on index
+            or on a key.
+        DataFrame.merge : Merge DataFrame or named Series objects with a
+            database-style join.
 
         Examples
         --------
         >>> idx1 = pd.Index([1, 2, 3])
         >>> idx2 = pd.Index([4, 5, 6])
         >>> idx1.join(idx2, how="outer")
         Index([1, 2, 3, 4, 5, 6], dtype='int64')
+        >>> idx1.join(other=idx2, how="outer", return_indexers=True)
+        (Index([1, 2, 3, 4, 5, 6], dtype='int64'),
+        array([ 0,  1,  2, -1, -1, -1]), array([-1, -1, -1,  0,  1,  2]))
         """
         other = ensure_index(other)
         sort = sort or how == "outer"