Merge pull request #650 from tannewt/merge_2x3.0.0-alpha.2

Merge in commits from 2.x branch.

12 files changed, 56 insertions, 32 deletions

diff --git a/shared-bindings/_stage/__init__.c b/shared-bindings/_stage/__init__.c
index 16e0b58d9..832b28771 100644
--- a/shared-bindings/_stage/__init__.c
+++ b/shared-bindings/_stage/__init__.c
@@ -32,7 +32,22 @@
 #include "Layer.h"
 #include "Text.h"
 
-//| .. currentmodule:: _stage
+//| :mod:`_stage` --- C-level helpers for animation of sprites on a stage
+//| =====================================================================
+//|
+//| .. module:: _stage
+//|   :synopsis: C-level helpers for animation of sprites on a stage
+//|   :platform: SAMD21
+//|
+//| The `_stage` module contains native code to speed-up the ```stage`` Library
+//| <https://github.com/python-ugame/circuitpython-stage>`_.
+//| Libraries
+//|
+//| .. toctree::
+//|     :maxdepth: 3
+//|
+//|     Layer
+//|     Text
 //|
 //| .. function:: render(x0, y0, x1, y1, layers, buffer, spi)
 //|
@@ -42,9 +57,9 @@
 //|     :param int y0: Top edge of the fragment.
 //|     :param int x1: Right edge of the fragment.
 //|     :param int y1: Bottom edge of the fragment.
-//|     :param list layers: A list of the `Layer` objects.
+//|     :param list layers: A list of the :py:class:`~_stage.Layer` objects.
 //|     :param bytearray buffer: A buffer to use for rendering.
-//|     :param SPI spi: The SPI device to use.
+//|     :param ~busio.SPI spi: The SPI bus to use.
 //|
 //|     Note that this function only sends the raw pixel data. Setting up
 //|     the display for receiving it and handling the chip-select and
diff --git a/shared-bindings/audiobusio/PDMIn.c b/shared-bindings/audiobusio/PDMIn.c
index bd89ab179..6f0a130e8 100644
--- a/shared-bindings/audiobusio/PDMIn.c
+++ b/shared-bindings/audiobusio/PDMIn.c
@@ -47,13 +47,13 @@
 //|   Create a PDMIn object associated with the given pins. This allows you to
 //|   record audio signals from the given pins. Individual ports may put further
 //|   restrictions on the recording parameters. The overall frequency is
-//|   determined by `frequency` x `oversample`, and the total must be 1MHz or
+//|   determined by `frequency` x ``oversample``, and the total must be 1MHz or
 //|   higher, so `frequency` must be a minimum of 16000.
 //|
 //|   :param ~microcontroller.Pin clock_pin: The pin to output the clock to
 //|   :param ~microcontroller.Pin data_pin: The pin to read the data from
 //|   :param int frequency: Target frequency of the resulting samples. Check `frequency` for actual value.
-//|   Minimum frequency is about 16000 Hz.
+//|     Minimum frequency is about 16000 Hz.
 //|   :param int bit_depth: Final number of bits per sample. Must be divisible by 8
 //|   :param bool mono: True when capturing a single channel of audio, captures two channels otherwise
 //|   :param int oversample: Number of single bit samples to decimate into a final sample. Must be divisible by 8
@@ -182,8 +182,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiobusio_pdmin___exit___obj, 4, 4,
 //|     audio at the given rate. For internal flash, writing all 1s to the file
 //|     before recording is recommended to speed up writes.
 //|
-//|    :return: The number of samples recorded. If this is less than `destination_length`,
-//|    some samples were missed due to processing time.
+//|     :return: The number of samples recorded. If this is less than ``destination_length``,
+//|       some samples were missed due to processing time.
 //|
 STATIC mp_obj_t audiobusio_pdmin_obj_record(mp_obj_t self_obj, mp_obj_t destination, mp_obj_t destination_length) {
     audiobusio_pdmin_obj_t *self = MP_OBJ_TO_PTR(self_obj);
diff --git a/shared-bindings/audiobusio/__init__.c b/shared-bindings/audiobusio/__init__.c
index 70606e496..bdd999b04 100644
--- a/shared-bindings/audiobusio/__init__.c
+++ b/shared-bindings/audiobusio/__init__.c
@@ -34,7 +34,7 @@
 #include "shared-bindings/audiobusio/PDMIn.h"
 
 //| :mod:`audiobusio` --- Support for audio input and output over digital bus
-//| =================================================
+//| =========================================================================
 //|
 //| .. module:: audiobusio
 //|   :synopsis: Support for audio input and output over digital bus
diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c
index c2889bb12..52c145d6d 100644
--- a/shared-bindings/busio/SPI.c
+++ b/shared-bindings/busio/SPI.c
@@ -258,7 +258,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 2, busio_spi_write);
 //|
 //|     :param bytearray buffer: Read data into this buffer
 //|     :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]``
-//|     :param int end: End of the slice; this index is not included 
+//|     :param int end: End of the slice; this index is not included
 //|     :param int write_value: Value to write while reading. (Usually ignored.)
 //|
 STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -304,7 +304,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 2, busio_spi_readinto);
 //|     :param bytearray buffer_out: Write out the data in this buffer
 //|     :param bytearray buffer_in: Read data into this buffer
 //|     :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]``
-//|     :param int out_end: End of the slice; this index is not included 
+//|     :param int out_end: End of the slice; this index is not included
 //|     :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]``
 //|     :param int in_end: End of the slice; this index is not included
 //|
diff --git a/shared-bindings/gamepad/GamePad.c b/shared-bindings/gamepad/GamePad.c
index bdc3359fb..a03b9318d 100644
--- a/shared-bindings/gamepad/GamePad.c
+++ b/shared-bindings/gamepad/GamePad.c
@@ -49,8 +49,8 @@ gamepad_obj_t* gamepad_singleton = NULL;
 //|
 //|
 //|     pad = gamepad.GamePad(
-//|         digitalio.DigitalInOut(board.D0),
-//|         digitalio.DigitalInOut(board.D1),
+//|         digitalio.DigitalInOut(board.D10),
+//|         digitalio.DigitalInOut(board.D11),
 //|     )
 //|
 //|     y = 0
@@ -63,8 +63,9 @@ gamepad_obj_t* gamepad_singleton = NULL;
 //|             y += 1
 //|             print(y)
 //|         time.sleep(0.1)
-//|         while pad.get_pressed():
+//|         while buttons:
 //|             # Wait for all buttons to be released.
+//|             buttons = pad.get_pressed()
 //|             time.sleep(0.1)
 //|
 
diff --git a/shared-bindings/help.c b/shared-bindings/help.c
index a3ae94797..cdd9a4a93 100644
--- a/shared-bindings/help.c
+++ b/shared-bindings/help.c
@@ -26,6 +26,15 @@
 
 #include "genhdr/mpversion.h"
 
+//| :func:`help` - Built-in method to provide helpful information
+//| ==============================================================
+//|
+//| .. method:: help(object=None)
+//|
+//|   Prints a help method about the given object. When ``object`` is none,
+//|   prints general port information.
+//|
+
 const char *circuitpython_help_text =
     "Welcome to Adafruit CircuitPython " MICROPY_GIT_TAG "!\r\n"
     "\r\n"
diff --git a/shared-bindings/index.rst b/shared-bindings/index.rst
index 1813d5699..a43270e15 100644
--- a/shared-bindings/index.rst
+++ b/shared-bindings/index.rst
@@ -17,9 +17,9 @@ SAMD51, SAMD51 Express, and ESP8266.
 NOTE 2: **SAMD** and/or **SAMD Express** without additional numbers, means both SAMD21 & SAMD51 versions
 are supported.
 
-=================  ===============
-Module             Supported Ports  				
-=================  ===============
+=================  ==============================
+Module             Supported Ports
+=================  ==============================
 `analogio`         **All Supported**
 `audiobusio`       **SAMD/SAMD Express**
 `audioio`          **SAMD Express**
@@ -43,7 +43,7 @@ Module             Supported Ports
 `touchio`          **SAMD/SAMD Express**
 `uheap`            **Debug (All)**
 `usb_hid`          **SAMD/SAMD Express**
-=================  ===============  				
+=================  ==============================
 
 Modules
 ---------
diff --git a/shared-bindings/math/__init__.c b/shared-bindings/math/__init__.c
index 76ba80c95..84827842f 100644
--- a/shared-bindings/math/__init__.c
+++ b/shared-bindings/math/__init__.c
@@ -176,7 +176,7 @@ STATIC NORETURN void math_error(void) {
   //|
   //| .. function:: pow(x, y)
   //|
-  //|   Returns `x` to the power of `y`.
+  //|   Returns ``x`` to the power of ``y``.
   //|
   //| .. function:: radians(x)
   //|
@@ -188,7 +188,7 @@ STATIC NORETURN void math_error(void) {
   //|
   //| .. function:: sqrt(x)
   //|
-  //|   Returns the square root of `x`.
+  //|   Returns the square root of ``x``.
   //|
   //| .. function:: tan(x)
   //|
@@ -299,25 +299,25 @@ MATH_FUN_2(ldexp, ldexp)
 
 // .. function:: erf(x)
 //
-//   Return the error function of `x`.
+//   Return the error function of ``x``.
 //
 MATH_FUN_1(erf, erf)
 
 // .. function:: erfc(x)
 //
-//   Return the complementary error function of `x`.
+//   Return the complementary error function of ``x``.
 //
 MATH_FUN_1(erfc, erfc)
 
 // .. function:: gamma(x)
 //
-//   Return the gamma function of `x`.
+//   Return the gamma function of ``x``.
 //
 MATH_FUN_1(gamma, tgamma)
 
 // .. function:: lgamma(x)
 //
-//   Return the natural logarithm of the gamma function of `x`.
+//   Return the natural logarithm of the gamma function of ``x``.
 //
 MATH_FUN_1(lgamma, lgamma)
 #endif
diff --git a/shared-bindings/microcontroller/Processor.c b/shared-bindings/microcontroller/Processor.c
index a311f1866..be685b0a8 100644
--- a/shared-bindings/microcontroller/Processor.c
+++ b/shared-bindings/microcontroller/Processor.c
@@ -37,7 +37,7 @@
 //| .. currentmodule:: microcontroller
 //|
 //| :class:`Processor` --- Microcontroller CPU information and control
-//| --------------------------------------------------------
+//| ------------------------------------------------------------------
 //|
 //| Get information about the microcontroller CPU and control it.
 //|
diff --git a/shared-bindings/microcontroller/__init__.c b/shared-bindings/microcontroller/__init__.c
index f261178f0..0c627cdf9 100644
--- a/shared-bindings/microcontroller/__init__.c
+++ b/shared-bindings/microcontroller/__init__.c
@@ -59,11 +59,12 @@
 //|
 //|     Pin
 //|     Processor
+//|     RunMode
 //|
 
 //| .. attribute:: cpu
 //|
-//|   CPU information and control, such as `cpu.temperature` and `cpu.frequency`
+//|   CPU information and control, such as ``cpu.temperature`` and ``cpu.frequency``
 //|   (clock frequency).
 //|   This object is the sole instance of `microcontroller.Processor`.
 //|
@@ -74,7 +75,7 @@
 //|   because this stops all other functions from completing. Think of this as an empty
 //|   ``while`` loop that runs for the specified ``(delay)`` time. If you have other
 //|   code or peripherals (e.g audio recording) that require specific timing or
-//|   processing while you are waiting, explore a different avenue such as using 
+//|   processing while you are waiting, explore a different avenue such as using
 //|   `time.sleep()`.
 //|
 STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) {
@@ -134,7 +135,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_on_next_reset_obj, mcu_on_next_reset);
 //| .. method:: reset()
 //|
 //|   Reset the microcontroller. After reset, the microcontroller will enter the
-//|   run mode last set by `one_next_reset`.
+//|   run mode last set by `on_next_reset`.
 //|
 //|   .. warning:: This may result in file system corruption when connected to a
 //|     host computer. Be very careful when calling this! Make sure the device
diff --git a/shared-bindings/random/__init__.c b/shared-bindings/random/__init__.c
index fe52c1fc0..cea437e98 100644
--- a/shared-bindings/random/__init__.c
+++ b/shared-bindings/random/__init__.c
@@ -79,7 +79,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(random_getrandbits_obj, random_getrandbits);
 //| .. function:: randrange(stop)
 //|               randrange(start, stop, step=1)
 //|
-//|   Returns a randomly selected integer from `range(start, stop, step)`.
+//|   Returns a randomly selected integer from ``range(start, stop, step)``.
 //|
 STATIC mp_obj_t random_randrange(size_t n_args, const mp_obj_t *args) {
     mp_int_t start = 0;
@@ -122,7 +122,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(random_randrange_obj, 1, 3, random_ra
 //| .. function:: randint(a, b)
 //|
 //|   Returns a randomly selected integer between a and b inclusive. Equivalent
-//|   to `randrange(a, b + 1, 1)`
+//|   to ``randrange(a, b + 1, 1)``
 //|
 STATIC mp_obj_t random_randint(mp_obj_t a_in, mp_obj_t b_in) {
     mp_int_t a = mp_obj_get_int(a_in);
diff --git a/shared-bindings/storage/__init__.c b/shared-bindings/storage/__init__.c
index 9c186a051..6f6a30da6 100644
--- a/shared-bindings/storage/__init__.c
+++ b/shared-bindings/storage/__init__.c
@@ -43,9 +43,7 @@
 //| The `storage` provides storage management functionality such as mounting and
 //| unmounting which is typically handled by the operating system hosting Python.
 //| CircuitPython does not have an OS, so this module provides this functionality
-//| directly. Its based on MicroPython's `uos` module but deliberately separates
-//| CPython compatible functionality (in `os`) from incompatible functionality
-//| (in `storage`).
+//| directly.
 //|
 
 //| .. function:: mount(filesystem, mount_path, \*, readonly=False)