DOC: Update documentation for rename (#13533)

Author: gliptak

doc/source/basics.rst

@@ -1159,14 +1159,17 @@ mapping (a dict or Series) or an arbitrary function.
    s.rename(str.upper)
 
 If you pass a function, it must return a value when called with any of the
-labels (and must produce a set of unique values). But if you pass a dict or
-Series, it need only contain a subset of the labels as keys:
+labels (and must produce a set of unique values). A dict or
+Series can also be used:
 
 .. ipython:: python
 
    df.rename(columns={'one' : 'foo', 'two' : 'bar'},
              index={'a' : 'apple', 'b' : 'banana', 'd' : 'durian'})
 
+If the mapping doesn't include a column/index label, it isn't renamed. Also
+extra labels in the mapping don't throw an error.
+
 The :meth:`~DataFrame.rename` method also provides an ``inplace`` named
 parameter that is by default ``False`` and copies the underlying data. Pass
 ``inplace=True`` to rename the data in place.

pandas/core/generic.py

@@ -555,8 +555,8 @@ def swaplevel(self, i=-2, j=-1, axis=0):
     _shared_docs['rename'] = """
         Alter axes input function or functions. Function / dict values must be
         unique (1-to-1). Labels not contained in a dict / Series will be left
-        as-is. Alternatively, change ``Series.name`` with a scalar
-        value (Series only).
+        as-is. Extra labels listed don't throw an error. Alternatively, change
+        ``Series.name`` with a scalar value (Series only).
 
         Parameters
         ----------
@@ -611,6 +611,11 @@ def swaplevel(self, i=-2, j=-1, axis=0):
         0  1  4
         1  2  5
         2  3  6
+        >>> df.rename(index=str, columns={"A": "a", "C": "c"})
+           a  B
+        0  1  4
+        1  2  5
+        2  3  6
         """
 
     @Appender(_shared_docs['rename'] % dict(axes='axes keywords for this'