DOC: correct merge_ordered example (#19401)

* issue #19393. update of incorrect documentation example for merge_ordered. adding a test corresponding to this example.

Author: raph-m

pandas/core/reshape/merge.py

@@ -194,19 +194,17 @@ def merge_ordered(left, right, on=None,
     5   e       3     b
 
     >>> merge_ordered(A, B, fill_method='ffill', left_by='group')
-       key  lvalue group  rvalue
-    0    a       1     a     NaN
-    1    b       1     a       1
-    2    c       2     a       2
-    3    d       2     a       3
-    4    e       3     a       3
-    5    f       3     a       4
-    6    a       1     b     NaN
-    7    b       1     b       1
-    8    c       2     b       2
-    9    d       2     b       3
-    10   e       3     b       3
-    11   f       3     b       4
+      group key  lvalue  rvalue
+    0     a   a       1     NaN
+    1     a   b       1     1.0
+    2     a   c       2     2.0
+    3     a   d       2     3.0
+    4     a   e       3     3.0
+    5     b   a       1     NaN
+    6     b   b       1     1.0
+    7     b   c       2     2.0
+    8     b   d       2     3.0
+    9     b   e       3     3.0
 
     Returns
     -------

pandas/tests/reshape/merge/test_merge_ordered.py

@@ -81,3 +81,21 @@ def test_empty_sequence_concat(self):
         pd.concat([pd.DataFrame()])
         pd.concat([None, pd.DataFrame()])
         pd.concat([pd.DataFrame(), None])
+
+    def test_doc_example(self):
+        left = DataFrame({'key': ['a', 'c', 'e', 'a', 'c', 'e'],
+                          'lvalue': [1, 2, 3] * 2,
+                          'group': list('aaabbb')})
+
+        right = DataFrame({'key': ['b', 'c', 'd'],
+                           'rvalue': [1, 2, 3]})
+
+        result = merge_ordered(left, right, fill_method='ffill',
+                               left_by='group')
+
+        expected = DataFrame({'group': list('aaaaabbbbb'),
+                              'key': ['a', 'b', 'c', 'd', 'e'] * 2,
+                              'lvalue': [1, 1, 2, 2, 3] * 2,
+                              'rvalue': [nan, 1, 2, 3, 3] * 2})
+
+        assert_frame_equal(result, expected)