DOC: add warning to append about inefficiency

pandas/core/frame.py

@@ -4618,10 +4618,10 @@ def append(self, other, ignore_index=False, verify_integrity=False):
         the DataFrame's index, the order of the columns in the resulting
         DataFrame will be unchanged.
 
-        Iteratively appending rows to a Dataframe can be more computationally
-        intense than a single concatenate. A better solution is to append those
-        rows to a list then concatenate the list with the original Dataframe
-        all at once.
+        Iteratively appending rows to a DataFrame can be more computationally
+        intensive than a single concatenate. A better solution is to append
+        those rows to a list and then concatenate the list with the original
+        DataFrame all at once.
 
         See also
         --------
@@ -4653,6 +4653,32 @@ def append(self, other, ignore_index=False, verify_integrity=False):
         2  5  6
         3  7  8
 
+        The following, while not a recommended method for generating a
+        DataFrame, illustrates how to efficiently generate a DataFrame from
+        multiple data sources.
+
+        Less efficient:
+        >>> df = pd.DataFrame(columns=['A'])
+        >>> for i in range(5):
+        ...     df = df.append({'A'}: i}, ignore_index=True)
+        >>> df
+           A
+        0  0
+        1  1
+        2  2
+        3  3
+        4  4
+
+        More efficient:
+        >>> pd.concat([pd.DataFrame([i], columns=['A']) for i in range(5)],
+        ...           ignore_index=True)
+           A
+        0  0
+        1  1
+        2  2
+        3  3
+        4  4
+
         """
         if isinstance(other, (Series, dict)):
             if isinstance(other, dict):

pandas/core/series.py

@@ -1524,9 +1524,10 @@ def append(self, to_append, ignore_index=False, verify_integrity=False):
 
         Notes
         -----
-        Iteratively appending to a series can be more computationally intense
+        Iteratively appending to a Series can be more computationally intensive
         than a single concatenate. A better solution is to append values to a
-        list then concatenate the list with the original series all at once.
+        list and then concatenate the list with the original series all at
+        once.
 
         See also
         --------