DOC: add warning to append about inefficiency

doc/make.py

@@ -150,10 +150,13 @@ def _remove_notebooks():
             print("Warning: Pandoc is not installed. Skipping notebooks.")
             _remove_notebooks()
 
-    yield
-    for nb, content in contents.items():
-        with open(nb, 'wt') as f:
-            f.write(content)
+    try:
+        yield
+    except BaseException:
+        for nb, content in contents.items():
+            with open(nb, 'wt') as f:
+                f.write(content)
+        raise
 
 
 def html():

pandas/core/frame.py

@@ -4618,6 +4618,11 @@ 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
+        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
         --------
         pandas.concat : General function to concatenate DataFrame, Series
@@ -4648,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

@@ -1522,6 +1522,18 @@ def append(self, to_append, ignore_index=False, verify_integrity=False):
         verify_integrity : boolean, default False
             If True, raise Exception on creating index with duplicates
 
+        Notes
+        -----
+        Iteratively appending to a Series can be more computationally intensive
+        than a single concatenate. A better solution is to append values to a
+        list and then concatenate the list with the original series all at
+        once.
+
+        See also
+        --------
+        pandas.concat : General function to concatenate DataFrame, Series
+            or Panel objects
+
         Returns
         -------
         appended : Series