DOC: Improve reshape\concat

pandas/core/reshape/concat.py

@@ -200,7 +200,7 @@ def concat(
 
  .. versionchanged:: 1.0.0
 
- Changed to not sort by default.
+  Changed to not sort by default.
 
  copy : bool, default True
  If False, do not copy data unnecessarily.
@@ -226,6 +226,10 @@ def concat(
  pandas objects can be found `here
  <https://pandas.pydata.org/pandas-docs/stable/user_guide/merging.html>`__.
 
+
+ It is not recommended to build DataFrames by adding single rows in a
+ for loop. Build a list of rows and make a DataFrame in a single concat.
+
  Examples
  --------
  Combine two ``Series``.
@@ -265,27 +269,27 @@ def concat(
  ... names=['Series name', 'Row ID'])
  Series name Row ID
  s1 0 a
- 1 b
+  1 b
  s2 0 c
- 1 d
+  1 d
  dtype: object
 
  Combine two ``DataFrame`` objects with identical columns.
 
  >>> df1 = pd.DataFrame([['a', 1], ['b', 2]],
  ... columns=['letter', 'number'])
  >>> df1
- letter number
+  letter number
  0 a 1
  1 b 2
  >>> df2 = pd.DataFrame([['c', 3], ['d', 4]],
  ... columns=['letter', 'number'])
  >>> df2
- letter number
+  letter number
  0 c 3
  1 d 4
  >>> pd.concat([df1, df2])
- letter number
+  letter number
  0 a 1
  1 b 2
  0 c 3
@@ -298,11 +302,11 @@ def concat(
  >>> df3 = pd.DataFrame([['c', 3, 'cat'], ['d', 4, 'dog']],
  ... columns=['letter', 'number', 'animal'])
  >>> df3
- letter number animal
+  letter number animal
  0 c 3 cat
  1 d 4 dog
  >>> pd.concat([df1, df3], sort=False)
- letter number animal
+  letter number animal
  0 a 1 NaN
  1 b 2 NaN
  0 c 3 cat
@@ -313,7 +317,7 @@ def concat(
  the ``join`` keyword argument.
 
  >>> pd.concat([df1, df3], join="inner")
- letter number
+  letter number
  0 a 1
  1 b 2
  0 c 3
@@ -325,7 +329,7 @@ def concat(
  >>> df4 = pd.DataFrame([['bird', 'polly'], ['monkey', 'george']],
  ... columns=['animal', 'name'])
  >>> pd.concat([df1, df4], axis=1)
- letter number animal name
+  letter number animal name
  0 a 1 bird polly
  1 b 2 monkey george
 
@@ -334,16 +338,30 @@ def concat(
 
  >>> df5 = pd.DataFrame([1], index=['a'])
  >>> df5
- 0
+  0
  a 1
  >>> df6 = pd.DataFrame([2], index=['a'])
  >>> df6
- 0
+  0
  a 2
  >>> pd.concat([df5, df6], verify_integrity=True)
  Traceback (most recent call last):
  ...
  ValueError: Indexes have overlapping values: ['a']
+
+ Append a single row to the end of a ``DataFrame`` object.
+
+ >>> df7 = pd.DataFrame({'a': 1, 'b': 2}, index=[0])
+ >>> df7
+ a b
+ 0 1 2
+ >>> new_row = pd.Series({'a': 3, 'b': 4})
+ >>> new_row
+ 0 3 4
+ >>> pd.concat([df7, new_row.to_frame().T], ignore_index=True)
+ a b
+ 0 1 2
+ 1 3 4
  """
  op = _Concatenator(
  objs,