Merge branch 'master' into capablerobot-usbhub

Author: osterwood

.gitignore

@@ -12,6 +12,8 @@
 
 # Packages
 ############
+dist/
+*.egg-info
 
 # Logs and Databases
 ######################
@@ -25,6 +27,7 @@
 ######################
 build/
 bin/
+circuitpython-stubs/
 
 # Test failure outputs
 ######################

.gitmodules

@@ -95,3 +95,6 @@
 [submodule "frozen/circuitpython-stage"]
 	path = frozen/circuitpython-stage
 	url = https://github.com/python-ugame/circuitpython-stage.git
+[submodule "ports/stm32f4/stm32f4"]
+	path = ports/stm32f4/stm32f4
+	url = https://github.com/adafruit/stm32f4.git

.travis.yml

@@ -21,18 +21,28 @@ git:
 # that SDK is shortest and add it there.  In the case of major re-organizations,
 # just try to make the builds "about equal in run time"
 env:
-  - TRAVIS_TESTS="unix docs translations website" TRAVIS_BOARDS="circuitplayground_express mini_sam_m4 grandcentral_m4_express pca10056 pca10059 feather_nrf52840_express makerdiary_nrf52840_mdk makerdiary_nrf52840_mdk_usb_dongle particle_boron particle_argon particle_xenon sparkfun_nrf52840_mini electronut_labs_papyr" TRAVIS_SDK=arm:nrf
-  - TRAVIS_BOARDS="metro_m0_express metro_m4_express metro_m4_airlift_lite pirkey_m0 trellis_m4_express trinket_m0 sparkfun_lumidrive sparkfun_redboard_turbo bast_pro_mini_m0" TRAVIS_SDK=arm
-  - TRAVIS_BOARDS="feather_radiofruit_zigbee gemma_m0 hallowing_m0_express itsybitsy_m0_express itsybitsy_m4_express meowmeow sam32 uchip escornabot_makech" TRAVIS_SDK=arm
-  - TRAVIS_BOARDS="feather_m0_express_crickit feather_m0_rfm69 feather_m0_rfm9x feather_m4_express arduino_zero arduino_mkr1300 arduino_mkrzero pewpew10 kicksat-sprite ugame10 robohatmm1" TRAVIS_SDK=arm
-  - TRAVIS_BOARDS="circuitplayground_express_crickit feather_m0_adalogger feather_m0_basic feather_m0_express catwan_usbstick pyportal sparkfun_samd21_mini sparkfun_samd21_dev pybadge" TRAVIS_SDK=arm
+  - TRAVIS_TESTS="unix docs translations website" TRAVIS_BOARDS="trinket_m0_haxpress circuitplayground_express mini_sam_m4 grandcentral_m4_express capablerobot_usbhub pygamer pca10056 pca10059 feather_nrf52840_express metro_nrf52840_express makerdiary_nrf52840_mdk makerdiary_nrf52840_mdk_usb_dongle particle_boron particle_argon particle_xenon sparkfun_nrf52840_mini electronut_labs_papyr electronut_labs_blip" TRAVIS_SDK=arm:nrf
+  - TRAVIS_BOARDS="metro_m0_express metro_m4_express metro_m4_airlift_lite pirkey_m0 trellis_m4_express trinket_m0 sparkfun_lumidrive sparkfun_redboard_turbo bast_pro_mini_m0 datum_distance pyruler" TRAVIS_SDK=arm
+  - TRAVIS_BOARDS="cp32-m4 feather_radiofruit_zigbee gemma_m0 hallowing_m0_express itsybitsy_m0_express itsybitsy_m4_express meowmeow sam32 uchip escornabot_makech pygamer_advance datum_imu snekboard" TRAVIS_SDK=arm
+  - TRAVIS_BOARDS="feather_m0_supersized feather_m0_express_crickit feather_m0_rfm69 feather_m0_rfm9x feather_m4_express arduino_zero arduino_mkr1300 arduino_mkrzero pewpew10 kicksat-sprite ugame10 robohatmm1_m0 robohatmm1_m4 datum_light" TRAVIS_SDK=arm
+  - TRAVIS_BOARDS="datalore_ip_m4 circuitplayground_express_crickit feather_m0_adalogger feather_m0_basic feather_m0_express catwan_usbstick pyportal sparkfun_samd21_mini sparkfun_samd21_dev pybadge pybadge_airlift datum_weather" TRAVIS_SDK=arm
 
 addons:
   artifacts:
     paths:
     - $(ls -d1 bin/*/*/* | tr "\n" ":")
     target_paths: /
 
+# Some deploy jobs take over 10 minutes so use this keep alive hack to make sure Travis doesn't kill us.
+before_deploy: |
+  function keep_alive() {
+    while true; do
+      echo -en "\a"
+      sleep 5
+    done
+  }
+  keep_alive &
+
 deploy:
   provider: releases
   api_key:
@@ -61,7 +71,6 @@ before_script:
   - function var_search () { case "$1" in *$2*) true;; *) false;; esac; }
   - sudo dpkg --add-architecture i386
 
-
   - (! var_search "${TRAVIS_SDK-}" arm || (wget https://s3.amazonaws.com/adafruit-circuit-python/gcc-arm-embedded_7-2018q2-1~xenial1_amd64.deb && sudo dpkg -i gcc-arm-embedded*_amd64.deb))
 
   # For huzzah builds
@@ -70,12 +79,16 @@ before_script:
 
   # For coverage testing (upgrade is used to get latest urllib3 version)
   - sudo apt-get install -y python3-pip
-  - pip3 install --user sh click
+  - pip3 install --user sh click setuptools
   - ([[ -z "$TRAVIS_TESTS" ]] || sudo pip install --upgrade cpp-coveralls)
   - (! var_search "${TRAVIS_TESTS-}" docs || sudo apt-get install -y librsvg2-bin)
-  - (! var_search "${TRAVIS_TESTS-}" docs || pip install --user Sphinx sphinx-rtd-theme recommonmark sphinxcontrib-svg2pdfconverter)
+  - (! var_search "${TRAVIS_TESTS-}" docs || pip3 install --user Sphinx sphinx-rtd-theme recommonmark sphinxcontrib-svg2pdfconverter)
   - (! var_search "${TRAVIS_TESTS-}" translations || pip3 install --user polib)
 
+  # Check if there's any board missing in TRAVIS_BOARDS
+  - cd tools && python3 -u travis_new_boards_check.py
+  - cd ..
+
   # report some good version numbers to the build
   - gcc --version
   - (! var_search "${TRAVIS_SDK-}" arm || arm-none-eabi-gcc --version)

Makefile

@@ -1,4 +1,4 @@
-# Makefile for Sphinx documentation
+# Top-level Makefile for documentation builds and miscellaneous tasks.
 #
 
 # You can set these variables from the command line.
@@ -17,6 +17,13 @@ CONFDIR      = .
 FORCE         = -E
 VERBOSE       = -v
 
+# path to generated type stubs
+STUBDIR       = circuitpython-stubs
+# Run "make VALIDATE= stubs" to avoid validating generated stub files
+VALIDATE      = -v
+# path to pypi source distributions
+DISTDIR       = dist
+
 # Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the
 # full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the
 # executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
@@ -31,7 +38,7 @@ I18NSPHINXOPTS  = $(BASEOPTS)
 
 TRANSLATE_SOURCES = extmod lib main.c ports/atmel-samd ports/nrf py shared-bindings shared-module supervisor
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext stubs
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -60,6 +67,7 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(STUBDIR) $(DISTDIR) *.egg-info
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -196,10 +204,18 @@ pseudoxml:
 all-source:
 
 locale/circuitpython.pot: all-source
-	find $(TRANSLATE_SOURCES) -iname "*.c" | xargs xgettext -L C -s --add-location=file --keyword=translate -o circuitpython.pot -p locale
+	find $(TRANSLATE_SOURCES) -iname "*.c" -print0 | (LC_ALL=C sort -z) | xargs -0 xgettext -L C -s --add-location=file --keyword=translate -o circuitpython.pot -p locale
 
 translate: locale/circuitpython.pot
 	for po in $(shell ls locale/*.po); do msgmerge -U $$po -s --no-fuzzy-matching --add-location=file locale/circuitpython.pot; done
 
 check-translate: locale/circuitpython.pot $(wildcard locale/*.po)
 	$(PYTHON) tools/check_translations.py $^
+
+stubs:
+	rst2pyi $(VALIDATE) shared-bindings/ $(STUBDIR)
+	python setup.py sdist
+
+update-frozen-libraries:
+	@echo "Updating all frozen libraries to latest tagged version."
+	cd frozen; for library in *; do cd $$library; ../../tools/git-checkout-latest-tag.sh; cd ..; done

README.rst

@@ -115,8 +115,8 @@ Behavior
    output is written to ``boot_out.txt``.
 -  ``code.py`` (or ``main.py``) is run after every reload until it
    finishes or is interrupted. After it is done running, the vm and
-   hardware is reinitialized. **This means you cannot read state from
-   ``code.py`` in the REPL anymore.** CircuitPython's goal for this
+   hardware is reinitialized. **This means you cannot read state from**
+   ``code.py`` **in the REPL anymore.** CircuitPython's goal for this
    change includes reduce confusion about pins and memory being used.
 -  After ``code.py`` the REPL can be entered by pressing any key. It no
    longer shares state with ``code.py`` so it is a fresh vm.
@@ -131,9 +131,9 @@ Behavior
    ``samd.disable_autoreload()``)
 -  Entering the REPL after the main code is finished requires a key press which enters the REPL and
    disables autoreload.
--  Main is one of these: ``code.txt``, **``code.py``**, ``main.py``,
+-  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 is one of these: ``settings.txt``, ``settings.py``, ``boot.py``,
    ``boot.txt``
 
 API

conf.py

@@ -13,6 +13,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import json
 import sys
 import os
 
@@ -24,8 +25,20 @@
 sys.path.insert(0, os.path.abspath('docs'))
 sys.path.insert(0, os.path.abspath('.'))
 
+import shared_bindings_matrix
+
 master_doc = 'docs/index'
 
+# Grab the JSON values to use while building the module support matrix
+# in 'shared-bindings/index.rst'
+
+#modules_support_matrix = shared_bindings_matrix.support_matrix_excluded_boards()
+modules_support_matrix = shared_bindings_matrix.support_matrix_by_board()
+
+html_context = {
+    'support_matrix': modules_support_matrix
+}
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -40,7 +53,9 @@
     'sphinxcontrib.rsvgconverter',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
-    'sphinx.ext.coverage'
+    'sphinx.ext.coverage',
+    'rstjinja',
+    'c2rst'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -49,8 +64,7 @@
 # The suffix of source filenames.
 source_suffix = ['.rst', '.md', '.c', '.h']
 
-source_parsers = {'.md': CommonMarkParser,
-                  '.c': "c2rst.CStrip", '.h': "c2rst.CStrip"}
+source_parsers = {'.md': CommonMarkParser}
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -84,6 +98,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = ["**/build*",
+                    ".git",
                     ".venv",
                     ".direnv",
                     "docs/README.md",
@@ -121,6 +136,10 @@
                     "ports/nrf/nrfx",
                     "ports/nrf/peripherals",
                     "ports/nrf/usb",
+                    "ports/stm32f4/stm32f4",
+                    "ports/stm32f4/peripherals",
+                    "ports/stm32f4/ref",
+                    "ports/stm32f4/README.md",
                     "ports/pic16bit",
                     "ports/qemu-arm",
                     "ports/stm32",

docs/c2rst.py

@@ -1,19 +1,31 @@
-import sphinx.parsers
+def c2rst(app, docname, source):
+    """ Pre-parse '.c' & '.h' files that contain rST source.
+    """
+    # Make sure we're outputting HTML
+    if app.builder.format != 'html':
+        return
 
-class CStrip(sphinx.parsers.Parser):
-    def __init__(self):
-        self.rst_parser = sphinx.parsers.RSTParser()
+    fname = app.env.doc2path(docname)
+    if (not fname.endswith(".c") and
+        not fname.endswith(".h")):
+            #print("skipping:", fname)
+            return
 
-    def parse(self, inputstring, document):
-        # This setting is missing starting with Sphinx 1.7.1 so we set it ourself.
-        document.settings.tab_width = 4
-        document.settings.character_level_inline_markup = False
-        stripped = []
-        for line in inputstring.split("\n"):
-            line = line.strip()
-            if line == "//|":
-                stripped.append("")
-            elif line.startswith("//| "):
-                stripped.append(line[len("//| "):])
-        stripped = "\r\n".join(stripped)
-        self.rst_parser.parse(stripped, document)
+    src = source[0]
+
+    stripped = []
+    for line in src.split("\n"):
+        line = line.strip()
+        if line == "//|":
+            stripped.append("")
+        elif line.startswith("//| "):
+            stripped.append(line[len("//| "):])
+    stripped = "\r\n".join(stripped)
+
+    rendered = app.builder.templates.render_string(
+        stripped, app.config.html_context
+    )
+    source[0] = rendered
+
+def setup(app):
+    app.connect("source-read", c2rst)

docs/design_guide.rst

@@ -60,6 +60,7 @@ For example, a user can then use ``deinit()```::
 
     import digitalio
     import board
+    import time
 
     led = digitalio.DigitalInOut(board.D13)
     led.direction = digitalio.Direction.OUTPUT
@@ -79,6 +80,7 @@ Alternatively, using a ``with`` statement ensures that the hardware is deinitial
 
     import digitalio
     import board
+    import time
 
     with digitalio.DigitalInOut(board.D13) as led:
         led.direction = digitalio.Direction.OUTPUT

docs/library/builtins.rst

@@ -182,7 +182,7 @@ Exceptions
 
 .. exception:: OSError
 
-    |see_cpython| `OSError`. CircuitPython doesn't implement the ``errno``
+    |see_cpython| :py:class:`cpython:OSError`. CircuitPython doesn't implement the ``errno``
     attribute, instead use the standard way to access exception arguments:
     ``exc.args[0]``.
 
@@ -198,11 +198,11 @@ Exceptions
 
 .. exception:: SystemExit
 
-    |see_cpython| :py:class:`python:SystemExit`.
+    |see_cpython| :py:class:`cpython:SystemExit`.
 
 .. exception:: TypeError
 
-    |see_cpython| :py:class:`python:TypeError`.
+    |see_cpython| :py:class:`cpython:TypeError`.
 
 .. exception:: ValueError
 

docs/library/network.rst

@@ -5,6 +5,7 @@
 .. include:: ../templates/unsupported_in_circuitpython.inc
 
 .. module:: network
+   :noindex:
    :synopsis: network configuration
 
 This module provides network drivers and routing configuration. To use this