docs: Backport PR bbcmicrobit#725 to V1 docs. (bbcmicrobit#735)

Original commit title: docs: fix missing pin methods and improve docs (bbcmicrobit#725)
Original commit hash: caa8e1c

- ~~fix missing space in directive that caused methods to be omitted.~~
- recast the get_mode() return values as their Python values rather than
  C names which aren't defined in Python.
- ~~remove duplicate class definition for MicroBitAnalogDigitalPin.~~

Cherry-picked from the v2-docs branch.

Co-authored-by: Matt Hillsdon <[email protected]>

Author: microbit-carlos

docs/pin.rst

@@ -152,10 +152,10 @@ its own to that.
 
         Returns the pin mode. When a pin is used for a specific function, like
         writing a digital value, or reading an analog value, the pin mode
-        changes. Pins can have one of the following modes: ``MODE_UNUSED``,
-        ``MODE_WRITE_ANALOG``, ``MODE_READ_DIGITAL``, ``MODE_WRITE_DIGITAL``,
-        ``MODE_DISPLAY``, ``MODE_BUTTON``, ``MODE_MUSIC``, ``MODE_AUDIO_PLAY``,
-        ``MODE_TOUCH``, ``MODE_I2C``, ``MODE_SPI``.
+        changes. Pins can have one of the following modes: ``"unused"``,
+        ``"analog"``, ``"read_digital"``, ``"write_digital"``,
+        ``"display"``, ``"button"``, ``"music"``, ``"audio"``,
+        ``"touch"``, ``"i2c"``, ``"spi"``.
 
     .. py:method:: write_analog(value)