Fixed some documentation/formatting issues, clarified the purpose of …

…the test case.

doc/source/contributing.rst

@@ -525,8 +525,9 @@ run this slightly modified command::
 
    git diff master --name-only -- '*.py' | grep 'pandas/' | xargs flake8
 
-Note that on Windows, `grep`, `xargs`, and other tools are likely unavailable.
-However, this has been shown to work on smaller commits::
+Note that on Windows, ``grep``, ``xargs``, and other tools are likely
+unavailable. However, this has been shown to work on smaller commits in the
+standard Windows command line::
 
     git diff master -u -- "*.py" | flake8 --diff
 

doc/source/whatsnew/v0.20.3.txt

@@ -51,7 +51,6 @@ Indexing
 ^^^^^^^^
 
 - Bug in ``Float64Index`` causing an empty array instead of ``None`` to be returned from ``.get(np.nan)`` on a Series whose index did not contain any ``NaN`` s (:issue:`8569`)
-- Fixed a bug that prevented joining on a categorical MultiIndex (:issue:`16627`).
 
 I/O
 ^^^
@@ -79,6 +78,7 @@ Sparse
 Reshaping
 ^^^^^^^^^
 
+- Bug in joining on a ``MultiIndex`` with a ``category`` dtype for a level (:issue:`16627`).
 
 
 Numeric

pandas/tests/test_join.py

@@ -207,12 +207,13 @@ def test_merge_join_categorical_multiindex():
          'Factor': [1.1, 1.2, 1.3, 1.4, 1.5, 1.6]}
     b = DataFrame(b).set_index(['Cat', 'Int'])['Factor']
 
-    c = merge(a, b.reset_index(), left_on=['Cat1', 'Int1'],
-              right_on=['Cat', 'Int'], how='left')
-    d = a.join(b, on=['Cat1', 'Int1'])
-    c = c.drop(['Cat', 'Int'], axis=1)
-    assert_frame_equal(c, d)
+    expected = merge(a, b.reset_index(), left_on=['Cat1', 'Int1'],
+                     right_on=['Cat', 'Int'], how='left')
+    result = a.join(b, on=['Cat1', 'Int1'])
+    expected = expected.drop(['Cat', 'Int'], axis=1)
+    assert_frame_equal(expected, result)
 
+    # Same test, but with ordered categorical
     a = {'Cat1': Categorical(['a', 'b', 'a', 'c', 'a', 'b'],
                              ['b', 'a', 'c'],
                              ordered=True),
@@ -226,8 +227,8 @@ def test_merge_join_categorical_multiindex():
          'Factor': [1.1, 1.2, 1.3, 1.4, 1.5, 1.6]}
     b = DataFrame(b).set_index(['Cat', 'Int'])['Factor']
 
-    c = merge(a, b.reset_index(), left_on=['Cat1', 'Int1'],
-              right_on=['Cat', 'Int'], how='left')
-    d = a.join(b, on=['Cat1', 'Int1'])
-    c = c.drop(['Cat', 'Int'], axis=1)
-    assert_frame_equal(c, d)
+    expected = merge(a, b.reset_index(), left_on=['Cat1', 'Int1'],
+                     right_on=['Cat', 'Int'], how='left')
+    result = a.join(b, on=['Cat1', 'Int1'])
+    expected = expected.drop(['Cat', 'Int'], axis=1)
+    assert_frame_equal(expected, result)