Merge pull request #863 from dhalbert/3.0_doc_updates

RTD documentation updates

8 files changed, 74 insertions, 86 deletions

diff --git a/docs/design_guide.rst b/docs/design_guide.rst
index a1524eaa2..e7b3832bc 100644
--- a/docs/design_guide.rst
+++ b/docs/design_guide.rst
@@ -441,10 +441,10 @@ buffers.
 Examples
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-ustruct.pack
+struct.pack
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use `ustruct.pack_into` instead of `ustruct.pack`.
+Use `struct.pack_into` instead of `struct.pack`.
 
 Sensor properties and units
 --------------------------------------------------------------------------------
diff --git a/docs/library/array.rst b/docs/library/array.rst
index dfaef0ff6..0f1310b68 100644
--- a/docs/library/array.rst
+++ b/docs/library/array.rst
@@ -1,8 +1,6 @@
 :mod:`array` -- arrays of numeric data
 ======================================
 
-.. include:: ../templates/unsupported_in_circuitpython.inc
-
 .. module:: array
    :synopsis: efficient arrays of numeric data
 
diff --git a/docs/library/builtins.rst b/docs/library/builtins.rst
index 83246afc9..36a84bc0c 100644
--- a/docs/library/builtins.rst
+++ b/docs/library/builtins.rst
@@ -1,18 +1,14 @@
 Builtin functions and exceptions
 ================================
 
-.. warning::
-
-    These builtins are inherited from MicroPython and may not work in CircuitPython
-    as documented or at all! If work differently from CPython, then their behavior
-    may change.
-
 All builtin functions and exceptions are described here. They are also
 available via ``builtins`` module.
 
 Functions and types
 -------------------
 
+Not all of these functions and types are turned on in all CircuitPython ports, for space reasons.
+
 .. function:: abs()
 
 .. function:: all()
@@ -62,6 +58,8 @@ Functions and types
 
 .. class:: frozenset()
 
+`frozenset()` is not enabled on non-Express CircuitPython boards.
+
 .. function:: getattr()
 
 .. function:: globals()
@@ -80,12 +78,12 @@ Functions and types
 
    .. classmethod:: from_bytes(bytes, byteorder)
 
-      In MicroPython, `byteorder` parameter must be positional (this is
+      In CircuitPython, `byteorder` parameter must be positional (this is
       compatible with CPython).
 
    .. method:: to_bytes(size, byteorder)
 
-      In MicroPython, `byteorder` parameter must be positional (this is
+      In CircuitPython, `byteorder` parameter must be positional (this is
       compatible with CPython).
 
 .. function:: isinstance()
@@ -130,6 +128,8 @@ Functions and types
 
 .. function:: reversed()
 
+`reversed()` is not enabled on non-Express CircuitPython boards.
+
 .. function:: round()
 
 .. class:: set()
@@ -182,7 +182,7 @@ Exceptions
 
 .. exception:: OSError
 
-    |see_cpython| `OSError`. MicroPython doesn't implement ``errno``
+    |see_cpython| `OSError`. CircuitPython doesn't implement the ``errno``
     attribute, instead use the standard way to access exception arguments:
     ``exc.args[0]``.
 
diff --git a/docs/library/gc.rst b/docs/library/gc.rst
index 01bd925e9..1a6c3d68c 100644
--- a/docs/library/gc.rst
+++ b/docs/library/gc.rst
@@ -31,7 +31,7 @@ Functions
    .. admonition:: Difference to CPython
       :class: attention
 
-      This function is MicroPython extension.
+      This function is a MicroPython extension.
 
 .. function:: mem_free()
 
@@ -41,7 +41,7 @@ Functions
    .. admonition:: Difference to CPython
       :class: attention
 
-      This function is MicroPython extension.
+      This function is a MicroPython extension.
 
 .. function:: threshold([amount])
 
@@ -63,6 +63,6 @@ Functions
    .. admonition:: Difference to CPython
       :class: attention
 
-      This function is a MicroPython extension. CPython has a similar
+      This function is a a MicroPython extension. CPython has a similar
       function - ``set_threshold()``, but due to different GC
       implementations, its signature and semantics are different.
diff --git a/docs/library/index.rst b/docs/library/index.rst
index c7b6879aa..6c2e576e7 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -3,43 +3,74 @@
 MicroPython libraries
 =====================
 
+Python standard libraries and micro-libraries
+---------------------------------------------
+
+These libraries are inherited from MicroPython.
+They are similar to the standard Python libraries with the same name
+or with the "u" prefix dropped.
+They implement a subset of or a variant of the corresponding
+standard Python library.
+
 .. warning::
 
-    These modules are inherited from MicroPython and may not work in CircuitPython
-    as documented or at all! If they do work, they may change at any time.
+   Though these MicroPython-based libraries are available in CircuitPython,
+   their functionality may change in the future, perhaps significantly.
+   As CircuitPython continues to develop, new versions of these libraries will
+   be created that are more compliant with the standard Python libraries.
+   You may need to change your code later if you rely
+   on any non-standard functionality they currently provide.
 
+CircuitPython's goal long-term goalis that code written in CircuitPython
+using Python standard libraries will be runnable on CPython without changes.
 
-Python standard libraries and micro-libraries
----------------------------------------------
+Some libraries below are not enabled on CircuitPython builds with
+limited flash memory, usually on non-Express builds:
+``uerrno``, ``ure``.
+
+Some libraries are not currently enabled in any CircuitPython build, but may be in the future:
+``uio``, ``ujson``, ``uzlib``.
 
+Some libraries are only enabled only WiFi-capable ports (ESP8266, nRF)
+because they are typically used for network software:
+``binascii``, ``hashlib``, ``uheapq``, ``uselect``, ``ussl``.
+Not all of these are enabled on all WiFi-capable ports.
 
 .. toctree::
    :maxdepth: 1
 
    builtins.rst
+   uheapq.rst
    array.rst
-   gc.rst
-   sys.rst
    binascii.rst
    collections.rst
-   uerrno.rst
+   gc.rst
    hashlib.rst
-   uheapq.rst
+   sys.rst
+   uerrno.rst
    uio.rst
    ujson.rst
    ure.rst
    uselect.rst
    usocket.rst
    ussl.rst
-   ustruct.rst
    uzlib.rst
 
+Omitted functions in the ``string`` library
+-------------------------------------------
+
+A few string operations are not enabled on CircuitPython
+M0 non-Express builds, due to limited flash memory:
+``string.center()``, ``string.partition()``, ``string.splitlines()``,
+``string.reversed()``.
+
 
-MicroPython-specific libraries
-------------------------------
+CircuitPython/MicroPython-specific libraries
+--------------------------------------------
 
-Functionality specific to the MicroPython implementation is available in
-the following libraries.
+Functionality specific to the CircuitPython/MicroPython implementation is available in
+the following libraries. These libraries may change signficantly or be removed in future
+versions of CircuitPtyon.
 
 .. toctree::
    :maxdepth: 1
diff --git a/docs/library/sys.rst b/docs/library/sys.rst
index de2ec2dcd..bb92850b8 100644
--- a/docs/library/sys.rst
+++ b/docs/library/sys.rst
@@ -45,12 +45,12 @@ Constants
 .. data:: implementation
 
    Object with information about the current Python implementation. For
-   MicroPython, it has following attributes:
+   CircuitPython, it has following attributes:
 
-   * *name* - string "micropython"
+   * *name* - string "circuitpython"
    * *version* - tuple (major, minor, micro), e.g. (1, 7, 0)
 
-   This object is the recommended way to distinguish MicroPython from other
+   This object is the recommended way to distinguish CircuitPython from other
    Python implementations (note that it still may not exist in the very
    minimal ports).
 
@@ -58,13 +58,13 @@ Constants
       :class: attention
 
       CPython mandates more attributes for this object, but the actual useful
-      bare minimum is implemented in MicroPython.
+      bare minimum is implemented in CircuitPython.
 
 .. data:: maxsize
 
    Maximum value which a native integer type can hold on the current platform,
-   or maximum value representable by MicroPython integer type, if it's smaller
-   than platform max value (that is the case for MicroPython ports without
+   or maximum value representable by CircuitPython integer type, if it's smaller
+   than platform max value (that is the case for CircuitPython ports without
    long int support).
 
    This attribute is useful for detecting "bitness" of a platform (32-bit vs
@@ -96,11 +96,11 @@ Constants
 
 .. data:: platform
 
-   The platform that MicroPython is running on. For OS/RTOS ports, this is
+   The platform that CircuitPython is running on. For OS/RTOS ports, this is
    usually an identifier of the OS, e.g. ``"linux"``. For baremetal ports it
-   is an identifier of a board, e.g. ``"pyboard"`` for the original MicroPython
-   reference board. It thus can be used to distinguish one board from another.
-   If you need to check whether your program runs on MicroPython (vs other
+   is an identifier of the chip on a board, e.g. ``"MicroChip SAMD51"``.
+   It thus can be used to distinguish one board from another.
+   If you need to check whether your program runs on CircuitPython (vs other
    Python implementation), use `sys.implementation` instead.
 
 .. data:: stderr
diff --git a/docs/library/ustruct.rst b/docs/library/ustruct.rst
deleted file mode 100644
index c378a94bb..000000000
--- a/docs/library/ustruct.rst
+++ /dev/null
@@ -1,44 +0,0 @@
-:mod:`ustruct` -- pack and unpack primitive data types
-======================================================
-
-.. include:: ../templates/unsupported_in_circuitpython.inc
-
-.. module:: ustruct
-   :synopsis: pack and unpack primitive data types
-
-|see_cpython_module| :mod:`cpython:struct`.
-
-Supported size/byte order prefixes: ``@``, ``<``, ``>``, ``!``.
-
-Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``,
-``L``, ``q``, ``Q``, ``s``, ``P``, ``f``, ``d`` (the latter 2 depending
-on the floating-point support).
-
-Functions
----------
-
-.. function:: calcsize(fmt)
-
-   Return the number of bytes needed to store the given *fmt*.
-
-.. function:: pack(fmt, v1, v2, ...)
-
-   Pack the values *v1*, *v2*, ... according to the format string *fmt*.
-   The return value is a bytes object encoding the values.
-
-.. function:: pack_into(fmt, buffer, offset, v1, v2, ...)
-
-   Pack the values *v1*, *v2*, ... according to the format string *fmt*
-   into a *buffer* starting at *offset*. *offset* may be negative to count
-   from the end of *buffer*.
-
-.. function:: unpack(fmt, data)
-
-   Unpack from the *data* according to the format string *fmt*.
-   The return value is a tuple of the unpacked values.
-
-.. function:: unpack_from(fmt, data, offset=0)
-
-   Unpack from the *data* starting at *offset* according to the format string
-   *fmt*. *offset* may be negative to count from the end of *buffer*. The return
-   value is a tuple of the unpacked values.
diff --git a/docs/templates/unsupported_in_circuitpython.inc b/docs/templates/unsupported_in_circuitpython.inc
index 18c9215a8..1ed605d50 100644
--- a/docs/templates/unsupported_in_circuitpython.inc
+++ b/docs/templates/unsupported_in_circuitpython.inc
@@ -1,5 +1,8 @@
 .. warning::
 
-    This module is inherited from MicroPython and may not work in CircuitPython
-    as documented or at all! If they do work, they may change at any time. It is
-    unsupported.
+   Though this MicroPython-based library is available for use in CircuitPython,
+   its functionality may change in the future, perhaps significantly.
+   As CircuitPython continues to develop, it may be changed
+   to comply more closely with the corresponding standard Python library.
+   You may need to change your code later if you rely
+   on any non-standard functionality it currently provides.