docs/machine: Change sleep to lightsleep and add timeout arguments.

The machine.sleep() function can be misleading because it clashes with
time.sleep() which has quite different semantics.  So change it to
machine.lightsleep() which shows that it is closer in behaviour to
machine.deepsleep().

Also, add an optional argument to these two sleep functions to specify a
maximum time to sleep for.  This is a common operation and underlying
hardware usually has a special way of performing this operation.

The existing machine.sleep() function will remain for backwards
compatibility purposes, and it can simply be an alias for
machine.lightsleep() without arguments.  The behaviour will be the same.

docs/library/machine.rst

@@ -63,16 +63,31 @@ Power related functions
 
 .. function:: sleep()
 
-   Stops the CPU and disables all peripherals except for WLAN. Execution is resumed from
-   the point where the sleep was requested. For wake up to actually happen, wake sources
-   should be configured first.
+   .. note:: This function is deprecated, use `lightsleep()` instead with no arguments.
 
-.. function:: deepsleep()
+.. function:: lightsleep([time_ms])
+              deepsleep([time_ms])
 
-   Stops the CPU and all peripherals (including networking interfaces, if any). Execution
-   is resumed from the main script, just as with a reset. The reset cause can be checked
-   to know that we are coming from `machine.DEEPSLEEP`. For wake up to actually happen,
-   wake sources should be configured first, like `Pin` change or `RTC` timeout.
+   Stops execution in an attempt to enter a low power state.
+
+   If *time_ms* is specified then this will be the maximum time in milliseconds that
+   the sleep will last for.  Otherwise the sleep can last indefinitely.
+
+   With or without a timout, execution may resume at any time if there are events
+   that require processing.  Such events, or wake sources, should be configured before
+   sleeping, like `Pin` change or `RTC` timeout.
+
+   The precise behaviour and power-saving capabilities of lightsleep and deepsleep is
+   highly dependent on the underlying hardware, but the general properties are:
+
+   * A lightsleep has full RAM and state retention.  Upon wake execution is resumed
+     from the point where the sleep was requested, with all subsystems operational.
+
+   * A deepsleep may not retain RAM or any other state of the system (for example
+     peripherals or network interfaces).  Upon wake execution is resumed from the main
+     script, similar to a hard or power-on reset. The `reset_cause()` function will
+     return `machine.DEEPSLEEP` and this can be used to distinguish a deepsleep wake
+     from other resets.
 
 .. function:: wake_reason()