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.
Examples are added to the beginning of the module docs, similarly to docs
for many other modules.
Improvements to grammar, style, and clarity. Some paragraphs are updated
with better suggestions. A warning added of the effect incorrect usage of
the module may have. Describe the fact that offset range used in one
defined structure is limited.
Otherwise there is really nothing that can be done, it can't be unlocked by
the user because there is no way to allocate memory to execute the unlock.
See issue #4205 and #4209.
With this commit there is now only one entry point into the whole
documentation, which describes the general MicroPython language, and then
from there there are links to information about specific platforms/ports.
This commit doesn't change content (almost, it does fix a few internal
links), it just reorganises things.
All concrete network classes are now moved to their own file (eg
network.WLAN.rst) and deconditionalised (remove ..only:: directives). This
makes the network documentation the same for all ports. After this change
there are no more "..only::" directives for different ports, and the only
difference among ports is the very front page of the docs.
The WiPy machine.Timer class is very different to the esp8266 and esp32
implementations which are better candidates for a general Timer class. By
moving the WiPy Timer docs to a completely separate file, under a new name
machine.TimerWiPy, it gives a clean slate to define and write the docs for
a better, general machine.Timer class. This is with the aim of eventually
providing documentation that does not have conditional parts to it,
conditional on the port.
While the new docs are being defined it makes sense to keep the WiPy docs,
since they describe its behaviour. Once the new Timer behaviour is defined
the WiPy code can be changed to match it, and then the TimerWiPy docs would
be removed.
The machine module should be standard across all ports so should have the
same set of classes in the docs. A special warning is added to the top of
the machine.SD class because it is not standardised and only available on
the cc3200 port.
It's fair to just provide a link to all available modules, regardless of
the port. Most of the existing ports (unix, stm32, esp8266, esp32) share
most of the same set of modules anyway, so no need to maintain separate
lists for them. And there's a big discussion at the start of this index
about modules not being available on a given port.
For port-specific modules, they can also be listed unconditionally because
they have headings that explicitly state they are only available on certain
ports.
