docs: Backport multiple minor V2 changes to V1 docs.

Author: microbit-carlos

docs/microbit_micropython_api.rst

@@ -49,8 +49,8 @@ These are both objects and have the following methods::
     # returns the running total of button presses, and resets this counter to zero
     button.get_presses()
 
-The LED display
----------------
+Display
+-------
 
 The LED display is exposed via the `display` object::
 
@@ -212,8 +212,8 @@ Images API::
     Image.ALL_CLOCKS
     Image.ALL_ARROWS
 
-The accelerometer
------------------
+Accelerometer
+-------------
 
 The accelerometer is accessed via the ``accelerometer`` object::
 
@@ -238,8 +238,8 @@ The accelerometer is accessed via the ``accelerometer`` object::
 The recognised gestures are: ``up``, ``down``, ``left``, ``right``, ``face up``, ``face down``, ``freefall``, ``3g``, ``6g``, ``8g``, ``shake``.
 
 
-The compass
------------
+Compass
+-------
 
 The compass is accessed via the `compass` object::
 

docs/speech.rst

@@ -1,17 +1,6 @@
 Speech
 ******
 
-.. warning::
-
-    WARNING! This is still work in progress; we reserve the right to change this API as development continues.
-
-    The quality of the speech is not great, merely "good enough". Given the
-    constraints of the device you may encounter memory errors and / or
-    unexpected extra sounds during playback. It's early days and we're
-    improving the code for the speech synthesiser all the time. Bug reports
-    and pull requests are most welcome.
-
-
 .. py:module:: speech
 
 This module makes microbit talk, sing and make other speech like sounds

docs/tutorials/music.rst

@@ -2,18 +2,23 @@ Music
 -----
 
 MicroPython on the BBC micro:bit comes with a powerful music and sound module.
-It's very easy to generate bleeps and bloops from the device *if you attach a
-speaker or passive piezo buzzer*. Use crocodile clips to attach pin 0 and GND
-to the positive and negative inputs on the speaker/buzzer - it doesn't matter
-which way round they are connected to a speaker, but a piezo buzzer may be
-polarized (check for a "+" marking the positive terminal).
+It's very easy to generate bleeps and bloops from the device by attaching a
+speaker or set of wired headphones.
+
+If you are attaching a speaker, a passive piezo buzzer, or headphones, you can
+use crocodile clips to attach pin 0 and GND to the positive and negative inputs.
+It doesn't matter which way round they are connected to a speaker, but a piezo
+buzzer may be polarized (check for a "+" marking the positive terminal).
 
 .. image:: pin0-gnd.png
+    :width: 250px
+    :align: center
+    :alt: piezo connected to pin0 and GND
 
 .. note::
 
-    Do not attempt this with an active Piezo buzzer - such buzzers are only able to
-    play a single tone.
+    Do not attempt this with an active Piezo buzzer - such buzzers are only
+    able to play a single tone.
 
 Let's play some music::
 

examples/speech.py

@@ -1,3 +1,10 @@
+"""
+    speech.py
+    ~~~~~~~~
+    Simple speech example to make the micro:bit say, pronounce and sing
+    something. This example requires a speaker/buzzer/headphones connected
+    to P0 and GND,or the latest micro:bit device with built-in speaker.
+"""
 import speech
 from microbit import sleep