diff --git a/doc/python/shapes.md b/doc/python/shapes.md
index eecf12bd584..d0ae16b9e7d 100644
--- a/doc/python/shapes.md
+++ b/doc/python/shapes.md
@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.1'
-      jupytext_version: 1.1.1
+      jupytext_version: 1.2.1
   kernelspec:
     display_name: Python 3
     language: python
@@ -33,6 +33,26 @@ jupyter:
     thumbnail: thumbnail/shape.jpg
 ---
 
+### Filled Area Chart
+
+There are two ways to draw filled shapes: scatter traces and [layout.shapes](https://plot.ly/python/reference/#layout-shapes-items-shape-type) which is mostly useful for the 2d subplots, and defines the shape type to be drawn, and can be rectangle, circle, line, or path (a custom SVG path). You also can use [scatterpolar](https://plot.ly/python/polar-chart/#categorical-polar-chart), scattergeo, [scattermapbox](https://plot.ly/python/filled-area-on-mapbox/#filled-scattermapbox-trace) to draw filled shapes on any kind of subplots. To set an area to be filled with a solid color, you need to define [Scatter.fill="toself"](https://plot.ly/python/reference/#scatter-fill) that connects the endpoints of the trace into a closed shape. If `mode=line` (default value), then you need to repeat the initial point of a shape at the of the sequence to have a closed shape. 
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scatter(x=[0,1,2,0], y=[0,2,0,0], fill="toself"))
+fig.show()
+```
+
+You can have more shapes either by adding [more traces](https://plot.ly/python/filled-area-plots/) or interrupting the series with `None`.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scatter(x=[0,1,2,0,None,3,3,5,5,3], y=[0,2,0,0,None,0.5,1.5,1.5,0.5,0.5], fill="toself"))
+fig.show()
+```
+
 #### Vertical and Horizontal Lines Positioned Relative to the Axes
 
 ```python