docs: Add initial draft documentation for the WiPy.

This makes all common files "port-aware" using the .. only directive.

1 files changed, 186 insertions, 87 deletions

diff --git a/docs/library/pyb.SPI.rst b/docs/library/pyb.SPI.rst
index 70d6454015..d6f4bb9637 100644
--- a/docs/library/pyb.SPI.rst
+++ b/docs/library/pyb.SPI.rst
@@ -6,18 +6,32 @@ class SPI -- a master-driven serial protocol
 SPI is a serial protocol that is driven by a master.  At the physical level
 there are 3 lines: SCK, MOSI, MISO.
 
-See usage model of I2C; SPI is very similar.  Main difference is
-parameters to init the SPI bus::
+.. only:: port_pyboard
 
-    from pyb import SPI
-    spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0, crc=0x7)
+    See usage model of I2C; SPI is very similar.  Main difference is
+    parameters to init the SPI bus::
+    
+        from pyb import SPI
+        spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0, crc=0x7)
 
-Only required parameter is mode, SPI.MASTER or SPI.SLAVE.  Polarity can be
-0 or 1, and is the level the idle clock line sits at.  Phase can be 0 or 1
-to sample data on the first or second clock edge respectively.  Crc can be
-None for no CRC, or a polynomial specifier.
+    Only required parameter is mode, SPI.MASTER or SPI.SLAVE.  Polarity can be
+    0 or 1, and is the level the idle clock line sits at.  Phase can be 0 or 1
+    to sample data on the first or second clock edge respectively.  Crc can be
+    None for no CRC, or a polynomial specifier.
 
-Additional method for SPI::
+.. only:: port_wipy
+
+    See usage model of I2C; SPI is very similar.  Main difference is
+    parameters to init the SPI bus::
+    
+        from pyb import SPI
+        spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0)
+
+    Only required parameter is mode, must be SPI.MASTER.  Polarity can be 0 or 
+    1, and is the level the idle clock line sits at.  Phase can be 0 or 1 to 
+    sample data on the first or second clock edge respectively.
+
+Additional methods for SPI::
 
     data = spi.send_recv(b'1234')        # send 4 bytes and receive 4 bytes
     buf = bytearray(4)
@@ -28,22 +42,33 @@ Additional method for SPI::
 Constructors
 ------------
 
-.. class:: pyb.SPI(bus, ...)
-
-   Construct an SPI object on the given bus.  ``bus`` can be 1 or 2.
-   With no additional parameters, the SPI object is created but not
-   initialised (it has the settings from the last initialisation of
-   the bus, if any).  If extra arguments are given, the bus is initialised.
-   See ``init`` for parameters of initialisation.
-   
-   The physical pins of the SPI busses are:
-   
-     - ``SPI(1)`` is on the X position: ``(NSS, SCK, MISO, MOSI) = (X5, X6, X7, X8) = (PA4, PA5, PA6, PA7)``
-     - ``SPI(2)`` is on the Y position: ``(NSS, SCK, MISO, MOSI) = (Y5, Y6, Y7, Y8) = (PB12, PB13, PB14, PB15)``
-   
-   At the moment, the NSS pin is not used by the SPI driver and is free
-   for other use.
-
+.. only:: port_pyboard
+
+    .. class:: pyb.SPI(bus, ...)
+    
+       Construct an SPI object on the given bus.  ``bus`` can be 1 or 2.
+       With no additional parameters, the SPI object is created but not
+       initialised (it has the settings from the last initialisation of
+       the bus, if any).  If extra arguments are given, the bus is initialised.
+       See ``init`` for parameters of initialisation.
+       
+       The physical pins of the SPI busses are:
+       
+         - ``SPI(1)`` is on the X position: ``(NSS, SCK, MISO, MOSI) = (X5, X6, X7, X8) = (PA4, PA5, PA6, PA7)``
+         - ``SPI(2)`` is on the Y position: ``(NSS, SCK, MISO, MOSI) = (Y5, Y6, Y7, Y8) = (PB12, PB13, PB14, PB15)``
+       
+       At the moment, the NSS pin is not used by the SPI driver and is free
+       for other use.
+
+.. only:: port_wipy
+
+    .. class:: pyb.SPI(bus, ...)
+
+       Construct an SPI object on the given bus.  ``bus`` can be only 1.
+       With no additional parameters, the SPI object is created but not
+       initialised (it has the settings from the last initialisation of
+       the bus, if any).  If extra arguments are given, the bus is initialised.
+       See ``init`` for parameters of initialisation.
 
 Methods
 -------
@@ -51,73 +76,147 @@ Methods
 .. method:: spi.deinit()
 
    Turn off the SPI bus.
-
-.. method:: spi.init(mode, baudrate=328125, \*, prescaler, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None)
-
-   Initialise the SPI bus with the given parameters:
-   
-     - ``mode`` must be either ``SPI.MASTER`` or ``SPI.SLAVE``.
-     - ``baudrate`` is the SCK clock rate (only sensible for a master).
-     - ``prescaler`` is the prescaler to use to derive SCK from the APB bus frequency;
-       use of ``prescaler`` overrides ``baudrate``.
-     - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at.
-     - ``phase`` can be 0 or 1 to sample data on the first or second clock edge
-       respectively.
-     - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``.
-     - ``crc`` can be None for no CRC, or a polynomial specifier.
-
-   Note that the SPI clock frequency will not always be the requested baudrate.
-   The hardware only supports baudrates that are the APB bus frequency
-   (see :meth:`pyb.freq`) divided by a prescaler, which can be 2, 4, 8, 16, 32,
-   64, 128 or 256.  SPI(1) is on AHB2, and SPI(2) is on AHB1.  For precise
-   control over the SPI clock frequency, specify ``prescaler`` instead of
-   ``baudrate``.
-
-   Printing the SPI object will show you the computed baudrate and the chosen
-   prescaler.
-
-.. method:: spi.recv(recv, \*, timeout=5000)
-
-   Receive data on the bus:
    
-     - ``recv`` can be an integer, which is the number of bytes to receive,
-       or a mutable buffer, which will be filled with received bytes.
-     - ``timeout`` is the timeout in milliseconds to wait for the receive.
-   
-   Return value: if ``recv`` is an integer then a new buffer of the bytes received,
-   otherwise the same buffer that was passed in to ``recv``.
-
-.. method:: spi.send(send, \*, timeout=5000)
-
-   Send data on the bus:
-   
-     - ``send`` is the data to send (an integer to send, or a buffer object).
-     - ``timeout`` is the timeout in milliseconds to wait for the send.
-   
-   Return value: ``None``.
-
-.. method:: spi.send_recv(send, recv=None, \*, timeout=5000)
-
-   Send and receive data on the bus at the same time:
-   
-     - ``send`` is the data to send (an integer to send, or a buffer object).
-     - ``recv`` is a mutable buffer which will be filled with received bytes.
-       It can be the same as ``send``, or omitted.  If omitted, a new buffer will
-       be created.
-     - ``timeout`` is the timeout in milliseconds to wait for the receive.
-   
-   Return value: the buffer with the received bytes.
-
+.. only:: port_pyboard
+
+    .. method:: spi.init(mode, baudrate=328125, \*, prescaler, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None)
+    
+       Initialise the SPI bus with the given parameters:
+       
+         - ``mode`` must be either ``SPI.MASTER`` or ``SPI.SLAVE``.
+         - ``baudrate`` is the SCK clock rate (only sensible for a master).
+         - ``prescaler`` is the prescaler to use to derive SCK from the APB bus frequency;
+           use of ``prescaler`` overrides ``baudrate``.
+         - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at.
+         - ``phase`` can be 0 or 1 to sample data on the first or second clock edge
+           respectively.
+         - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``.
+         - ``crc`` can be None for no CRC, or a polynomial specifier.
+    
+       Note that the SPI clock frequency will not always be the requested baudrate.
+       The hardware only supports baudrates that are the APB bus frequency
+       (see :meth:`pyb.freq`) divided by a prescaler, which can be 2, 4, 8, 16, 32,
+       64, 128 or 256.  SPI(1) is on AHB2, and SPI(2) is on AHB1.  For precise
+       control over the SPI clock frequency, specify ``prescaler`` instead of
+       ``baudrate``.
+    
+       Printing the SPI object will show you the computed baudrate and the chosen
+       prescaler.
+
+.. only:: port_wipy
+
+    .. method:: spi.init(mode, baudrate=328125, \*, polarity=1, phase=0, bits=8, nss=SPI.ACTIVE_LOW)
+    
+       Initialise the SPI bus with the given parameters:
+       
+         - ``mode`` must be ``SPI.MASTER``.
+         - ``baudrate`` is the SCK clock rate.
+         - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at.
+         - ``phase`` can be 0 or 1 to sample data on the first or second clock edge
+           respectively.
+         - ``bits`` is the width of each transfer, accepted values are 8, 16 and 32.
+         - ``nss`` is the polarity of the slave select line. Can be ``SPI.ACTIVE_LOW``
+           or ``SPI.ACTIVE_HIGH``.
+    
+       Note that the SPI clock frequency will not always be the requested baudrate.
+       Printing the SPI object will show you the computed baudrate and the chosen
+       prescaler.
+
+.. only:: port_pyboard
+
+    .. method:: spi.recv(recv, \*, timeout=5000)
+    
+       Receive data on the bus:
+       
+         - ``recv`` can be an integer, which is the number of bytes to receive,
+           or a mutable buffer, which will be filled with received bytes.
+         - ``timeout`` is the timeout in milliseconds to wait for the receive.
+       
+       Return value: if ``recv`` is an integer then a new buffer of the bytes received,
+       otherwise the same buffer that was passed in to ``recv``.
+
+.. only:: port_wipy
+
+    .. method:: spi.recv(recv)
+    
+       Receive data on the bus:
+       
+         - ``recv`` can be an integer, which is the number of bytes to receive,
+           or a mutable buffer, which will be filled with received bytes.
+       
+       Return value: if ``recv`` is an integer then a new buffer of the bytes received,
+       otherwise the same buffer that was passed in to ``recv``.
+
+.. only:: port_pyboard
+
+    .. method:: spi.send(send, \*, timeout=5000)
+    
+       Send data on the bus:
+       
+         - ``send`` is the data to send (an integer to send, or a buffer object).
+         - ``timeout`` is the timeout in milliseconds to wait for the send.
+       
+       Return value: ``None``.
+
+.. only:: port_wipy
+
+    .. method:: spi.send(send)
+    
+       Send data on the bus:
+       
+         - ``send`` is the data to send (an integer to send, or a buffer object).
+       
+       Return value: ``None``.
+
+.. only:: port_pyboard
+
+    .. method:: spi.send_recv(send, recv=None, \*, timeout=5000)
+    
+       Send and receive data on the bus at the same time:
+       
+         - ``send`` is the data to send (an integer to send, or a buffer object).
+         - ``recv`` is a mutable buffer which will be filled with received bytes.
+           It can be the same as ``send``, or omitted.  If omitted, a new buffer will
+           be created.
+         - ``timeout`` is the timeout in milliseconds to wait for the receive.
+       
+       Return value: the buffer with the received bytes.
+
+.. only:: port_wipy
+
+    .. method:: spi.send_recv(send, recv=None)
+    
+       Send and receive data on the bus at the same time:
+       
+         - ``send`` is the data to send (an integer to send, or a buffer object).
+         - ``recv`` is a mutable buffer which will be filled with received bytes.
+           It can be the same as ``send``, or omitted.  If omitted, a new buffer will
+           be created.
+
+       Return value: the buffer with the received bytes.
 
 Constants
 ---------
 
-.. data:: SPI.MASTER
-.. data:: SPI.SLAVE
+.. only:: port_pyboard
+
+    .. data:: SPI.MASTER
+    .. data:: SPI.SLAVE
+    
+       for initialising the SPI bus to master or slave mode
+    
+    .. data:: SPI.LSB
+    .. data:: SPI.MSB
+    
+       set the first bit to be the least or most significant bit
 
-   for initialising the SPI bus to master or slave mode
+.. only:: port_wipy
 
-.. data:: SPI.LSB
-.. data:: SPI.MSB
+    .. data:: SPI.MASTER
 
-   set the first bit to be the least or most significant bit
+       for initialising the SPI bus to master
+    
+    .. data:: SPI.ACTIVE_LOW
+    .. data:: SPI.ACTIVE_HIGH
+    
+       decides the polarity of the NSS pin