addressed review

Author: emmanuelle

doc/python/images.md

@@ -313,7 +313,7 @@ It can be useful to add shapes to a layout image, for highlighting an object, dr
 
 In order to enable shape drawing, you need to
 - define a dragmode corresponding to a drawing tool (`'drawline'`,`'drawopenpath'`, `'drawclosedpath'`, `'drawcircle'`, or `'drawrect'`)
-- add modebar buttons corresponding to the drawing tools you wish to use.
+- add [modebar buttons](/python/configuration-options#add-optional-shapedrawing-buttons-to-modebar) corresponding to the drawing tools you wish to use.
 
 The style of new shapes is specified by the `newshape` layout attribute. Shapes can be selected and modified after they have been drawn. More details and examples are given in the [tutorial on shapes](/python/shapes#drawing-shapes-on-cartesian-plots).
 
@@ -327,7 +327,6 @@ img_width = 1600
 img_height = 900
 scale_factor = 0.5
 fig.add_layout_image(
-    dict(
         x=0,
         sizex=img_width,
         y=0,
@@ -336,7 +335,7 @@ fig.add_layout_image(
         yref="y",
         opacity=1.0,
         layer="below",
-        source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/bridge.jpg")
+        source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/bridge.jpg"
 )
 fig.update_xaxes(showgrid=False, range=(0, img_width))
 fig.update_yaxes(showgrid=False, scaleanchor='x', range=(img_height, 0))

doc/python/shapes.md

@@ -720,7 +720,7 @@ fig.show()
 
 _introduced in plotly 4.7_
 
-You can create layout shapes programatically, but you can also draw shapes manually by setting the `dragmode` to one of the shape-drawing modes: `'drawline'`,`'drawopenpath'`, `'drawclosedpath'`, `'drawcircle'`, or `'drawrect'`. If you need to switch between different shape-drawing or other dragmodes (panning, selecting, etc.), modebar buttons can be added in the `config` to select the dragmode. If you switch to a different dragmode such as pan or zoom, you will need to select the drawing tool in the modebar to go back to shape drawing.
+You can create layout shapes programatically, but you can also draw shapes manually by setting the `dragmode` to one of the shape-drawing modes: `'drawline'`,`'drawopenpath'`, `'drawclosedpath'`, `'drawcircle'`, or `'drawrect'`. If you need to switch between different shape-drawing or other dragmodes (panning, selecting, etc.), [modebar buttons can be added](/python/configuration-options#add-optional-shapedrawing-buttons-to-modebar) in the `config` to select the dragmode. If you switch to a different dragmode such as pan or zoom, you will need to select the drawing tool in the modebar to go back to shape drawing.
 
 This shape-drawing feature is particularly interesting for annotating graphs, in particular [image traces](/python/imshow) or [layout images](/python/images).
 
@@ -765,6 +765,8 @@ fig.show(config={'modeBarButtonsToAdd':['drawline',
 
 The layout `newshape` attribute controls the visual appearance of new shapes drawn by the user. `newshape` attributes have the same names as layout shapes.
 
+_Note on shape opacity_: having a new shape's opacity > 0.5 makes it possible to activate a shape by clicking inside the shape (for opacity <= 0.5 you have to click on the border of the shape), but you cannot start a new shape within an existing shape (which is possible for an opacity <= 0.5).
+
 ```python
 import plotly.graph_objects as go
 fig = go.Figure()
@@ -781,7 +783,7 @@ fig.add_annotation(
 # shape defined programatically
 fig.add_shape(line_color='yellow',
               fillcolor='turquoise',
-              opacity=0.8,
+              opacity=0.4,
               editable=True,
               x0=0, x1=1, y0=2, y1=3,
               xref='x1', yref='y1'
@@ -790,7 +792,7 @@ fig.update_layout(dragmode='drawrect',
                   # style of new shapes
                   newshape=dict(line_color='yellow',
                                 fillcolor='turquoise',
-                                opacity=0.8))
+                                opacity=0.5))
 fig.show(config={'modeBarButtonsToAdd':['drawline',
                                         'drawopenpath',
                                         'drawclosedpath',