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.
The UART.init() method is now included unconditionally and its wording
adjusted to better describe ports other than the cc3200.
UART.irq() is also included unconditionally, but this is currently only
available on the WiPy target.
By virtue of its name, the pyb module would only be available on a pyboard
and so does not need to have conditional "only" directives throughout its
documentation.
These conditionals were added mostly in
cfcf47c064 in the initial development of the
cc3200 port, which had the pyb module before it switched to the machine
module. And wipy only conditionals were removed from the pyb module
documentation in 4542643025, so there's no
need to retain any more conditionals.
Allow including crypto consts based on compilation settings. Disabled by
default to reduce code size; if one wants extra code readability, can
enable them.
These can be optionally specified, but all ports are expected to be able to
accept them, at the very least ignore, though handling of "type" param
(SOCK_STREAM vs SOCK_DGRAM) is recommended.
This can be used to select the output buffer behaviour of the DAC. The
default values are chosen to retain backwards compatibility with existing
behaviour.
Thanks to @peterhinch for the initial idea to add this feature.
Paul Sokolovsky
Damien George
Peter Hinch
Yonatan Goldschmidt
jcea
T S
Tom Collins