Split the examples into several sections.

Easier to follow.

Author: samuelsinayoko

pandas/core/frame.py

@@ -5195,17 +5195,6 @@ def stack(self, level=-1, dropna=True):
 
  Examples
  --------
- >>> multicol1 = pd.MultiIndex.from_tuples([('X', 'a'), ('X', 'b')])
- >>> df_multi_level_cols1 = pd.DataFrame([[0, 1], [2, 3]],
- ... index=['one', 'two'],
- ... columns=multicol1)
- >>> multicol2 = pd.MultiIndex.from_tuples([('X', 'a'), ('Y', 'b')])
- >>> df_multi_level_cols2 = pd.DataFrame([[0.0, 1.0], [2.0, 3.0]],
- ... index=['one', 'two'],
- ... columns=multicol2)
- >>> df_multi_level_cols3 = pd.DataFrame([[None, 1.0], [2.0, 3.0]],
- ... index=['one', 'two'],
- ... columns=multicol2)
 
  **Single level columns**
 
@@ -5226,6 +5215,13 @@ def stack(self, level=-1, dropna=True):
  b 3
  dtype: int64
 
+ **Multi level columns: simple case**
+
+ >>> multicol1 = pd.MultiIndex.from_tuples([('X', 'a'), ('X', 'b')])
+ >>> df_multi_level_cols1 = pd.DataFrame([[0, 1], [2, 3]],
+ ... index=['one', 'two'],
+ ... columns=multicol1)
+
  Stacking a dataframe with a multi-level column axis:
 
  >>> df_multi_level_cols1
@@ -5240,6 +5236,13 @@ def stack(self, level=-1, dropna=True):
  two a 2
  b 3
 
+ **Missing values**
+
+ >>> multicol2 = pd.MultiIndex.from_tuples([('X', 'a'), ('Y', 'b')])
+ >>> df_multi_level_cols2 = pd.DataFrame([[0.0, 1.0], [2.0, 3.0]],
+ ... index=['one', 'two'],
+ ... columns=multicol2)
+
  It is common to have missing values when stacking a dataframe
  with multi-level columns, as the stacked dataframe typically
  has more values than the original dataframe. Missing values
@@ -5257,6 +5260,8 @@ def stack(self, level=-1, dropna=True):
  two a 2.0 NaN
  b NaN 3.0
 
+ **Prescribing the level(s) to be stacked**
+
  The first parameter controls which level or levels are stacked:
 
  >>> df_multi_level_cols2.stack(0)
@@ -5272,6 +5277,13 @@ def stack(self, level=-1, dropna=True):
  Y b 3.0
  dtype: float64
 
+ **Dropping missing values**
+
+ >>> df_multi_level_cols3 = pd.DataFrame([[None, 1.0], [2.0, 3.0]],
+ ... index=['one', 'two'],
+ ... columns=multicol2)
+
+
  Note that rows where all values are missing are dropped by
  default but this behaviour can be controlled via the dropna
  keyword parameter: