Improve docs and update to CircuitPython.

Author: tannewt

README.md

@@ -1,9 +1,9 @@
 # Adafruit CircuitPython
 
-[![Build Status](https://travis-ci.org/adafruit/circuitpython.svg?branch=master)](https://travis-ci.org/adafruit/circuitpython)
+[![Build Status](https://travis-ci.org/adafruit/circuitpython.svg?branch=master)](https://travis-ci.org/adafruit/circuitpython) [![Doc Status](https://readthedocs.org/projects/circuitpython/badge/?version=latest)](http://circuitpython.readthedocs.io/)
 
 This is an open source derivative of [MicroPython](http://www.micropython.org)
-for use on educational development boards designed and sold by Adafruit
+for use on educational development boards designed and sold by [Adafruit](https://www.adafruit.com)
 including the [Arduino Zero](https://www.arduino.cc/en/Main/ArduinoBoardZero), [Adafruit Feather M0 Basic](https://www.adafruit.com/products/2772), [Adafruit Feather HUZZAH](https://www.adafruit.com/products/2821) and
 [Adafruit Feather M0 Bluefruit LE](https://www.adafruit.com/products/2995).
 
@@ -15,7 +15,7 @@ This project is in beta. Most APIs should be stable going forward.
 
 ## Documentation
 
-Guides and videos are available through the [Adafruit Learning System](https://learn.adafruit.com/) under the [CircuitPython category](https://learn.adafruit.com/category/circuitpython). An API reference is also available on [Read the Docs](http://circuitpython.readthedocs.io/en/latest/?).
+Guides and videos are available through the [Adafruit Learning System](https://learn.adafruit.com/) under the [CircuitPython category](https://learn.adafruit.com/category/circuitpython) and [MicroPython category](https://learn.adafruit.com/category/micropython). An API reference is also available on [Read the Docs](http://circuitpython.readthedocs.io/en/latest/?).
 
 ## Contributing
 See [CONTRIBUTING.md](https://github.com/adafruit/circuitpython/blob/master/CONTRIBUTING.md)
@@ -27,6 +27,24 @@ Contributors who follow the
 are welcome to submit pull requests and they will be promptly reviewed by
 project admins.
 
+## Differences from [MicroPython](https://github.com/micropython/micropython)
+
+* Port for Atmel SAMD21 (Commonly known as M0 in product names.)
+* No `machine` API on Atmel SAMD21 port.
+* Only supports Atmel SAMD21 and ESP8266 ports.
+* Unified hardware API: [`nativeio`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/nativeio/__init__.html), [`microcontroller`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/microcontroller/__init__.html), [`board`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/board/__init__.html), [`bitbangio`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/bitbangio/__init__.html) (Only available on atmel-samd21 and ESP8266 currently.)
+* Tracks MicroPython's releases (not master).
+* No module aliasing. (`uos` and `utime` are not available as `os` and `time` respectively.)
+* Modules with a CPython counterpart, such as `time`, are strict [subsets](https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html) of their [CPython version](https://docs.python.org/3.4/library/time.html?highlight=time#module-time). Therefore, code from CircuitPython is runnable on CPython but not necessarily the reverse.
+* tick count is available as [`time.monotonic()`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html#time.monotonic)
+* `os` only available as `uos`
+* atmel-samd21 features
+    * RGB status LED
+    * Auto-reset after file write over mass storage. (Disable with `samd.disable_autoreset()`)
+    * Wait state after boot and main run, before REPL.
+    * Main is one of these: code.txt, code.py, main.py, main.txt
+    * Boot is one of these: settings.txt, settings.py, boot.py, boot.txt
+
 ## Project Structure
 Here is an overview of the top-level directories.
 

atmel-samd/README.md renamed to atmel-samd/README.rst

@@ -1,31 +1,38 @@
-# SAMD21x18
+SAMD21x18
+=========
 
 This port brings MicroPython to SAMD21x18 based development boards including the
 Arduino Zero, Adafruit Feather M0 Basic and Adafruit M0 Bluefruit LE.
 
-## Building
+Building
+--------
 
 To build for the Arduino Zero:
 
     make
 
-To build for other boards you must change it by setting `BOARD`. For example:
+To build for other boards you must change it by setting ``BOARD``. For example:
 
     make BOARD=feather_m0_basic
 
-Board names are the directory names in the `boards` folder.
+Board names are the directory names in the `boards <https://github.com/adafruit/circuitpython/tree/master/atmel-samd/boards>`_ folder.
 
-## Deploying
+Deploying
+---------
+
+Arduino Bootloader
+^^^^^^^^^^^^^^^^^^
 
-### Arduino Bootloader
 If your board has an existing Arduino bootloader on it then you can use bossac
 to flash MicroPython. First, activate the bootloader. On Adafruit Feathers you
 can double click the reset button and the #13 will fade in and out. Finally,
 run bossac:
 
     tools/bossac_osx -e -w -v -b -R build-feather_m0_basic/firmware.bin
 
-### No Bootloader via GDB
+No Bootloader via GDB
+^^^^^^^^^^^^^^^^^^^^^
+
 This method works for loading MicroPython onto the Arduino Zero via the
 programming port rather than the native USB port.
 
@@ -45,9 +52,11 @@ In another terminal from `micropython/atmel-samd`:
     ...
     (gdb) continue
 
-## Connecting
+Connecting
+----------
 
-### Serial
+Serial
+^^^^^^
 
 All boards are currently configured to work over USB rather than UART. To
 connect to it from OSX do something like this:
@@ -57,7 +66,14 @@ connect to it from OSX do something like this:
 You may not see a prompt immediately because it doesn't know you connected. To
 get one either hit enter to get `>>>` or do CTRL-B to get the full header.
 
-### Mass storage
+Mass storage
+^^^^^^^^^^^^
 
 All boards will also show up as a mass storage device. Make sure to eject it
 before referring to any files.
+
+Port Specific modules
+---------------------
+
+.. toctree::
+    bindings/samd/__init__

atmel-samd/bindings/samd/__init__.c

@@ -35,20 +35,20 @@
 //|   :platform: SAMD21
 //|
 
-//|   .. method:: enable_autoreset()
+//| .. method:: enable_autoreset()
 //|
-//|     Enable autoreset based on USB file write activity.
+//|   Enable autoreset based on USB file write activity.
 //|
 STATIC mp_obj_t samd_enable_autoreset(void) {
     autoreset_enable();
     return mp_const_none;
 }
 MP_DEFINE_CONST_FUN_OBJ_0(samd_enable_autoreset_obj, samd_enable_autoreset);
 
-//|   .. method:: disable_autoreset()
+//| .. method:: disable_autoreset()
 //|
-//|     Disable autoreset based on USB file write activity until the next reset
-//|     or until `enable_autoreset` is called.
+//|   Disable autoreset based on USB file write activity until the next reset
+//|   or until `enable_autoreset` is called.
 //|
 STATIC mp_obj_t samd_disable_autoreset(void) {
     autoreset_disable();

conf.py

@@ -59,17 +59,18 @@
 #master_doc = 'index'
 
 # General information about the project.
-project = 'Adafruit\'s MicroPython'
-copyright = '2014-2016, MicroPython contributors (https://github.com/adafruit/micropython/graphs/contributors)'
+project = 'Adafruit CircuitPython'
+copyright = '2014-2017, MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)'
 
+# These are overwritten on ReadTheDocs.
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '1.8'
+version = '0.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.8.6'
+release = '0.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -83,7 +84,40 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["*/build-*", "atmel-samd/asf", "atmel-samd/**.c", "atmel-samd/**.h", "bare-arm", "cc3200", "cc3200/FreeRTOS", "cc3200/hal", "drivers", "esp8266", "examples", "extmod", "lib", "minimal", "mpy-cross", "pic16bit", "py", "qemu-arm", "stmhal", "stmhal/hal", "stmhal/cmsis", "stmhal/usbdev", "stmhal/usbhost", "teensy", "tests", "tools", "unix", "windows", "zephyr"]
+exclude_patterns = ["*/build-*",
+                    "atmel-samd/asf",
+                    "atmel-samd/asf_conf",
+                    "atmel-samd/common-hal",
+                    "atmel-samd/boards",
+                    "atmel-samd/QTouch",
+                    "atmel-samd/*.c",
+                    "atmel-samd/*.h",
+                    "bare-arm",
+                    "cc3200",
+                    "cc3200/FreeRTOS",
+                    "cc3200/hal",
+                    "drivers",
+                    "esp8266",
+                    "examples",
+                    "extmod",
+                    "lib",
+                    "minimal",
+                    "mpy-cross",
+                    "pic16bit",
+                    "py",
+                    "qemu-arm",
+                    "shared-module",
+                    "stmhal",
+                    "stmhal/hal",
+                    "stmhal/cmsis",
+                    "stmhal/usbdev",
+                    "stmhal/usbhost",
+                    "teensy",
+                    "tests",
+                    "tools",
+                    "unix",
+                    "windows",
+                    "zephyr"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

docs/drivers.rst

@@ -5,7 +5,7 @@ These are drivers available in separate GitHub repos.
 
 .. toctree::
 
-    Register Library <http://adafruit-micropython-register.readthedocs.io/en/latest/>
+    Register Library <https://circuitpython.readthedocs.io/projects/register/en/latest/>
     RGB Displays <http://micropython-rgb.readthedocs.io/>
     Analog-to-digital converters: ADS1015 and ADS1115 <http://micropython-ads1015.readthedocs.io/>
     DS3231 Real-time Clock (Precision RTC) <https://circuitpython.readthedocs.io/projects/ds3231/en/latest/>

index.rst

@@ -24,7 +24,6 @@ docs are low-level API docs and may link out to separate getting started guides.
     docs/common_hal
     docs/drivers.rst
     docs/supported_ports.rst
-    docs/unsupported_ports.rst
     docs/library/index.rst
     README
     CONTRIBUTING

license.rst

@@ -1,9 +1,9 @@
-MicroPython license information
-===============================
+MicroPython & CircuitPython license information
+===============================================
 
 The MIT License (MIT)
 
-Copyright (c) 2013-2015 Damien P. George, and others
+Copyright (c) 2013-2017 Damien P. George, and others
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

shared-bindings/help.c

@@ -27,10 +27,13 @@
 #include "lib/utils/pyhelp.h"
 #include "shared-bindings/help.h"
 
-//|   .. method:: help(object=None)
+//| :func:`help` - Built-in method to provide helpful information
+//| ========================================================
 //|
-//|     Prints a help method about the given object. When ``object`` is none,
-//|     prints general port information.
+//| .. method:: help(object=None)
+//|
+//|   Prints a help method about the given object. When ``object`` is none,
+//|   prints general port information.
 //|
 STATIC mp_obj_t pyb_help(uint n_args, const mp_obj_t *args) {
     if (n_args == 0) {

shared-bindings/index.rst

@@ -10,3 +10,4 @@ follow.
     :maxdepth: 3
 
     */__init__
+    help

shared-bindings/microcontroller/__init__.c

@@ -43,7 +43,7 @@
 //|
 //| .. module:: microcontroller
 //|   :synopsis: Pin references and core functionality
-//|   :platform: SAMD21
+//|   :platform: SAMD21, ESP8266
 //|
 //| The `microcontroller` module defines the pins from the perspective of the
 //| microcontroller. See `board` for board-specific pin mappings.
@@ -56,10 +56,10 @@
 //|     Pin
 //|
 
-//|   .. method:: delay_us(delay)
+//| .. method:: delay_us(delay)
 //|
-//|     Dedicated delay method used for very short delays. DO NOT do long delays
-//|     because it will stall any concurrent code.
+//|   Dedicated delay method used for very short delays. DO NOT do long delays
+//|   because it will stall any concurrent code.
 //|
 STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) {
     uint32_t delay = mp_obj_get_int(delay_obj);
@@ -70,19 +70,19 @@ STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_delay_us_obj, mcu_delay_us);
 
-//|   .. method:: disable_interrupts()
+//| .. method:: disable_interrupts()
 //|
-//|     Disable all interrupts. Be very careful, this can stall everything.
+//|   Disable all interrupts. Be very careful, this can stall everything.
 //|
 STATIC mp_obj_t mcu_disable_interrupts(void) {
     common_hal_mcu_disable_interrupts();
     return mp_const_none;
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_disable_interrupts_obj, mcu_disable_interrupts);
 
-//|   .. method:: enable_interrupts()
+//| .. method:: enable_interrupts()
 //|
-//|     Enable the interrupts that were enabled at the last disable.
+//|   Enable the interrupts that were enabled at the last disable.
 //|
 STATIC mp_obj_t mcu_enable_interrupts(void) {
     common_hal_mcu_enable_interrupts();