docs: Import documentation from source-code inline comments.

The inline docs (prefixed with /// in .c files) have been converted to
RST format and put in the docs subdirectory.

docs/conf.py

@@ -60,7 +60,7 @@ copyright = '2014, Damien P. George'
 # The short X.Y version.
 version = '1.3'
 # The full version, including alpha/beta/rc tags.
-release = '1.3.1'
+release = '1.3.5'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/index.rst

@@ -14,10 +14,11 @@ Software
 --------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    general.rst
    tutorial/index.rst
+   library/index.rst
 
 .. 
 ..  - Reference for the [pyb module](module/pyb/ "pyb module").

docs/library/cmath.rst

+:mod:`cmath` --- mathematical functions for complex numbers
+===========================================================
+
+.. module:: cmath
+   :synopsis: mathematical functions for complex numbers
+
+The ``cmath`` module provides some basic mathematical funtions for
+working with complex numbers.
+
+
+Functions
+---------
+
+.. function:: cos(z)
+
+   Return the cosine of ``z``.
+
+.. function:: exp(z)
+
+   Return the exponential of ``z``.
+
+.. function:: log(z)
+
+   Return the natural logarithm of ``z``.  The branch cut is along the negative real axis.
+
+.. function:: log10(z)
+
+   Return the base-10 logarithm of ``z``.  The branch cut is along the negative real axis.
+
+.. function:: phase(z)
+
+   Returns the phase of the number ``z``, in the range (-pi, +pi].
+
+.. function:: polar(z)
+
+   Returns, as a tuple, the polar form of ``z``.
+
+.. function:: rect(r, phi)
+
+   Returns the complex number with modulus ``r`` and phase ``phi``.
+
+.. function:: sin(z)
+
+   Return the sine of ``z``.
+
+.. function:: sqrt(z)
+
+   Return the square-root of ``z``.
+
+
+Constants
+---------
+
+.. data:: e
+
+   base of the natural logarithm
+
+.. data:: pi
+
+   the ratio of a circle's circumference to its diameter

docs/library/gc.rst

+:mod:`gc` --- control the garbage collector
+===========================================
+
+.. module:: gc
+   :synopsis: control the garbage collector
+
+
+
+Functions
+---------
+
+.. function:: collect()
+
+   Run a garbage collection.
+
+.. function:: disable()
+
+   Disable the garbage collector.
+
+.. function:: enable()
+
+   Enable the garbage collector.
+
+.. function:: mem_alloc()
+
+   Return the number of bytes of heap RAM that are allocated.
+
+.. function:: mem_free()
+
+   Return the number of bytes of available heap RAM.

docs/library/index.rst

+Micro Python libraries
+======================
+
+Python standard libraries
+-------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   cmath.rst
+   gc.rst
+   math.rst
+   os.rst
+   select.rst
+   sys.rst
+   time.rst
+
+Micro Python reduced libraries
+------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   usocket.rst
+   uheapq.rst
+   ujson.rst
+
+Libraries specific to the pyboard
+---------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   pyb.rst
+   network.rst

docs/library/math.rst

+:mod:`math` --- mathematical functions
+======================================
+
+.. module:: math
+   :synopsis: mathematical functions
+
+The ``math`` module provides some basic mathematical funtions for
+working with floating-point numbers.
+
+
+Functions
+---------
+
+.. function:: acos(x)
+
+
+.. function:: acosh(x)
+
+
+.. function:: asin(x)
+
+
+.. function:: asinh(x)
+
+
+.. function:: atan(x)
+
+
+.. function:: atan2(y, x)
+
+
+.. function:: atanh(x)
+
+
+.. function:: ceil(x)
+
+
+.. function:: copysign(x, y)
+
+
+.. function:: cos(x)
+
+
+.. function:: cosh(x)
+
+
+.. function:: degrees(x)
+
+
+.. function:: erf(x)
+
+   Return the error function of ``x``.
+
+.. function:: erfc(x)
+
+   Return the complementary error function of ``x``.
+
+.. function:: exp(x)
+
+
+.. function:: expm1(x)
+
+
+.. function:: fabs(x)
+
+
+.. function:: floor(x)
+
+
+.. function:: fmod(x, y)
+
+
+.. function:: frexp(x)
+
+   Converts a floating-point number to fractional and integral components.
+
+.. function:: gamma(x)
+
+   Return the gamma function of ``x``.
+
+.. function:: isfinite(x)
+
+
+.. function:: isinf(x)
+
+
+.. function:: isnan(x)
+
+
+.. function:: ldexp(x, exp)
+
+
+.. function:: lgamma(x)
+
+   return the natural logarithm of the gamma function of ``x``.
+
+.. function:: log(x)
+
+
+.. function:: log10(x)
+
+
+.. function:: log2(x)
+
+
+.. function:: modf(x)
+
+
+.. function:: pow(x, y)
+
+   Returns ``x`` to the power of ``y``.
+
+.. function:: radians(x)
+
+
+.. function:: sin(x)
+
+
+.. function:: sinh(x)
+
+
+.. function:: sqrt(x)
+
+   Returns the square root of ``x``.
+
+.. function:: tan(x)
+
+
+.. function:: tanh(x)
+
+
+.. function:: trunc(x)
+
+
+
+Constants
+---------
+
+.. data:: e
+
+   base of the natural logarithm
+
+.. data:: pi
+
+   the ratio of a circle's circumference to its diameter

docs/library/network.rst

+****************************************
+:mod:`network` --- network configuration
+****************************************
+
+.. module:: network
+   :synopsis: network configuration
+
+This module provides network drivers and routing configuration.
+
+
+class CC3k
+==========
+
+Constructors
+------------
+
+.. class:: CC3k(spi, pin_cs, pin_en, pin_irq)
+
+   Initialise the CC3000 using the given SPI bus and pins and return a CC3k object.
+
+
+Methods
+-------
+
+.. method:: cc3k.connect(ssid, key=None, \*, security=WPA2, bssid=None)
+
+
+class WIZnet5k
+==============
+
+This class allows you to control WIZnet5x00 Ethernet adaptors based on
+the W5200 and W5500 chipsets (only W5200 tested).
+
+Example usage::
+
+    import wiznet5k
+    w = wiznet5k.WIZnet5k()
+    print(w.ipaddr())
+    w.gethostbyname('micropython.org')
+    s = w.socket()
+    s.connect(('192.168.0.2', 8080))
+    s.send('hello')
+    print(s.recv(10))
+
+
+Constructors
+------------
+
+.. class:: WIZnet5k(spi, pin_cs, pin_rst)
+
+   Create and return a WIZnet5k object.
+
+
+Methods
+-------
+
+.. method:: wiznet5k.ipaddr([(ip, subnet, gateway, dns)])
+
+   Get/set IP address, subnet mask, gateway and DNS.
+
+.. method:: wiznet5k.regs()
+
+   Dump WIZnet5k registers.

docs/library/os.rst

+:mod:`os` --- basic "operating system" services
+===============================================
+
+.. module:: os
+   :synopsis: basic "operating system" services
+
+The ``os`` module contains functions for filesystem access and ``urandom``.
+
+The filesystem has ``/`` as the root directory, and the available physical
+drives are accessible from here.  They are currently:
+
+    /flash      -- the internal flash filesystem
+    /sd         -- the SD card (if it exists)
+
+On boot up, the current directory is ``/flash`` if no SD card is inserted,
+otherwise it is ``/sd``.
+
+
+Functions
+---------
+
+.. function:: chdir(path)
+
+   Change current directory.
+
+.. function:: getcwd()
+
+   Get the current directory.
+
+.. function:: listdir([dir])
+
+   With no argument, list the current directory.  Otherwise list the given directory.
+
+.. function:: mkdir(path)
+
+   Create a new directory.
+
+.. function:: remove(path)
+
+   Remove a file.
+
+.. function:: rmdir(path)
+
+   Remove a directory.
+
+.. function:: stat(path)
+
+   Get the status of a file or directory.
+
+.. function:: sync()
+
+   Sync all filesystems.
+
+.. function:: urandom(n)
+
+   Return a bytes object with n random bytes, generated by the hardware
+   random number generator.
+
+
+Constants
+---------
+
+.. data:: sep
+
+   separation character used in paths

docs/library/pyb.ADC.rst

+class ADC =-- analog to digital conversion: read analog values on a pin
+=======================================================================
+
+Usage::
+
+    import pyb
+
+    adc = pyb.ADC(pin)              # create an analog object from a pin
+    val = adc.read()                # read an analog value
+
+    adc = pyb.ADCAll(resolution)    # creale an ADCAll object
+    val = adc.read_channel(channel) # read the given channel
+    val = adc.read_core_temp()      # read MCU temperature
+    val = adc.read_core_vbat()      # read MCU VBAT
+    val = adc.read_core_vref()      # read MCU VREF
+
+
+Constructors
+------------
+
+.. class:: pyb.ADC(pin)
+
+   Create an ADC object associated with the given pin.
+   This allows you to then read analog values on that pin.
+
+
+Methods
+-------
+
+.. method:: adc.read()
+
+   Read the value on the analog pin and return it.  The returned value
+   will be between 0 and 4095.
+
+.. method:: adc.read_timed(buf, freq)
+
+   Read analog values into the given buffer at the given frequency. Buffer
+   can be bytearray or array.array for example. If a buffer with 8-bit elements
+   is used, sample resolution will be reduced to 8 bits.
+   
+   Example::
+   
+       adc = pyb.ADC(pyb.Pin.board.X19)    # create an ADC on pin X19
+       buf = bytearray(100)                # create a buffer of 100 bytes
+       adc.read_timed(buf, 10)             # read analog values into buf at 10Hz
+                                           #   this will take 10 seconds to finish
+       for val in buf:                     # loop over all values
+           print(val)                      # print the value out
+   
+   This function does not allocate any memory.

docs/library/pyb.Accel.rst

+class Accel --- accelerometer control
+=====================================
+
+Accel is an object that controls the accelerometer.  Example usage::
+
+    accel = pyb.Accel()
+    for i in range(10):
+        print(accel.x(), accel.y(), accel.z())
+
+Raw values are between -32 and 31.
+
+
+Constructors
+------------
+
+.. class:: pyb.Accel()
+
+   Create and return an accelerometer object.
+   
+   Note: if you read accelerometer values immediately after creating this object
+   you will get 0.  It takes around 20ms for the first sample to be ready, so,
+   unless you have some other code between creating this object and reading its
+   values, you should put a ``pyb.delay(20)`` after creating it.  For example::
+   
+       accel = pyb.Accel()
+       pyb.delay(20)
+       print(accel.x())
+
+
+Methods
+-------
+
+.. method:: accel.filtered_xyz()
+
+   Get a 3-tuple of filtered x, y and z values.
+
+.. method:: accel.tilt()
+
+   Get the tilt register.
+
+.. method:: accel.x()
+
+   Get the x-axis value.
+
+.. method:: accel.y()
+
+   Get the y-axis value.
+
+.. method:: accel.z()
+
+   Get the z-axis value.

docs/library/pyb.CAN.rst

+class CAN --- controller area network communication bus
+=======================================================
+
+CAN implements the standard CAN communications protocol.  At
+the physical level it consists of 2 lines: RX and TX.  Note that
+to connect the pyboard to a CAN bus you must use a CAN transceiver
+to convert the CAN logic signals from the pyboard to the correct
+voltage levels on the bus.
+
+Note that this driver does not yet support filter configuration
+(it defaults to a single filter that lets through all messages),
+or bus timing configuration (except for setting the prescaler).
+
+Example usage (works without anything connected)::
+
+    from pyb import CAN
+    can = pyb.CAN(1, pyb.CAN.LOOPBACK)
+    can.send('message!', 123)   # send message to id 123
+    can.recv(0)                 # receive message on FIFO 0
+
+
+Constructors
+------------
+
+.. class:: pyb.CAN(bus, ...)
+
+   Construct a CAN object on the given bus.  ``bus`` can be 1-2, or 'YA' or 'YB'.
+   With no additional parameters, the CAN 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 CAN busses are:
+   
+     - ``CAN(1)`` is on ``YA``: ``(RX, TX) = (Y3, Y4) = (PB8, PB9)``
+     - ``CAN(2)`` is on ``YB``: ``(RX, TX) = (Y5, Y6) = (PB12, PB13)``
+
+
+Methods
+-------
+
+.. method:: can.init(mode, extframe=False, prescaler=100, \*, sjw=1, bs1=6, bs2=8)
+
+   Initialise the CAN bus with the given parameters:
+   
+     - ``mode`` is one of:  NORMAL, LOOPBACK, SILENT, SILENT_LOOPBACK
+
+   If ``extframe`` is True then the bus uses extended identifiers in the frames (29 bits).
+   Otherwise it uses standard 11 bit identifiers.
+
+.. method:: can.deinit()
+
+   Turn off the CAN bus.
+
+.. method:: can.any(fifo)
+
+   Return ``True`` if any message waiting on the FIFO, else ``False``.
+
+.. method:: can.recv(fifo, \*, timeout=5000)
+
+   Receive data on the bus:
+   
+     - ``fifo`` is an integer, which is the FIFO to receive on
+     - ``timeout`` is the timeout in milliseconds to wait for the receive.
+   
+   Return value: buffer of data bytes.
+
+.. method:: can.send(send, addr, \*, timeout=5000)
+
+   Send a message on the bus:
+   
+     - ``send`` is the data to send (an integer to send, or a buffer object).
+     - ``addr`` is the address to send to
+     - ``timeout`` is the timeout in milliseconds to wait for the send.
+   
+   Return value: ``None``.
+
+
+Constants
+---------
+
+.. data:: CAN.NORMAL
+.. data:: CAN.LOOPBACK
+.. data:: CAN.SILENT
+.. data:: CAN.SILENT_LOOPBACK
+
+   the mode of the CAN bus

docs/library/pyb.DAC.rst

+class DAC --- digital to analog conversion
+==========================================
+
+The DAC is used to output analog values (a specific voltage) on pin X5 or pin X6.
+The voltage will be between 0 and 3.3V.
+
+*This module will undergo changes to the API.*
+
+Example usage::
+
+    from pyb import DAC
+
+    dac = DAC(1)            # create DAC 1 on pin X5
+    dac.write(128)          # write a value to the DAC (makes X5 1.65V)
+
+To output a continuous sine-wave::
+
+    import math
+    from pyb import DAC
+
+    # create a buffer containing a sine-wave
+    buf = bytearray(100)
+    for i in range(len(buf)):
+        buf[i] = 128 + int(127 \* math.sin(2 \* math.pi \* i / len(buf)))
+
+    # output the sine-wave at 400Hz
+    dac = DAC(1)
+    dac.write_timed(buf, 400 \* len(buf), mode=DAC.CIRCULAR)
+
+
+Constructors
+------------
+