fix doc build; reorganize placement of library docs

conf.py

@@ -441,7 +441,7 @@ texinfo_documents = [
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"cpython": ('https://docs.python.org/3/', None),
+intersphinx_mapping = {"python": ('https://docs.python.org/3/', None),
                        "register": ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None),
                        "typing": ('https://circuitpython.readthedocs.io/projects/adafruit-circuitpython-typing/en/latest/', None)}
 

docs/index.rst

@@ -19,6 +19,7 @@ Full Table of Contents
    :caption: API and Usage
 
    ../shared-bindings/index.rst
+   library/index.rst
    supported_ports.rst
    troubleshooting.rst
    libraries.rst
@@ -32,13 +33,12 @@ Full Table of Contents
    design_guide
    porting
    common_hal
+   reference/mpyfiles.rst
+   reference/glossary.rst
 
 .. toctree::
    :maxdepth: 2
-   :caption: MicroPython specific
+   :caption: Python stand
-
-   library/index.rst
-   reference/glossary.rst
 
 .. toctree::
    :maxdepth: 1

docs/library/binascii.rst

@@ -35,7 +35,7 @@ Functions
 
    Encode binary data in base64 format, as in `RFC 3548
    <https://tools.ietf.org/html/rfc3548.html>`_. Returns the encoded data
-   followed by a newline character if ``newline``is true, as a bytes object.
+   followed by a newline character if ``newline`` is true, as a bytes object.
 
 .. function:: crc32(data, value=0, /)
 

docs/library/btree.rst

@@ -1,161 +0,0 @@
-:mod:`btree` -- simple BTree database
-=====================================
-
-.. include:: ../templates/unsupported_in_circuitpython.inc
-
-.. module:: btree
-   :synopsis: simple BTree database
-
-The ``btree`` module implements a simple key-value database using external
-storage (disk files, or in general case, a random-access `stream`). Keys are
-stored sorted in the database, and besides efficient retrieval by a key
-value, a database also supports efficient ordered range scans (retrieval
-of values with the keys in a given range). On the application interface
-side, BTree database work as close a possible to a way standard `dict`
-type works, one notable difference is that both keys and values must
-be `bytes` objects (so, if you want to store objects of other types, you
-need to serialize them to `bytes` first).
-
-The module is based on the well-known BerkelyDB library, version 1.xx.
-
-Example::
-
-    import btree
-
-    # First, we need to open a stream which holds a database
-    # This is usually a file, but can be in-memory database
-    # using io.BytesIO, a raw flash partition, etc.
-    # Oftentimes, you want to create a database file if it doesn't
-    # exist and open if it exists. Idiom below takes care of this.
-    # DO NOT open database with "a+b" access mode.
-    try:
-        f = open("mydb", "r+b")
-    except OSError:
-        f = open("mydb", "w+b")
-
-    # Now open a database itself
-    db = btree.open(f)
-
-    # The keys you add will be sorted internally in the database
-    db[b"3"] = b"three"
-    db[b"1"] = b"one"
-    db[b"2"] = b"two"
-
-    # Assume that any changes are cached in memory unless
-    # explicitly flushed (or database closed). Flush database
-    # at the end of each "transaction".
-    db.flush()
-
-    # Prints b'two'
-    print(db[b"2"])
-
-    # Iterate over sorted keys in the database, starting from b"2"
-    # until the end of the database, returning only values.
-    # Mind that arguments passed to values() method are *key* values.
-    # Prints:
-    #   b'two'
-    #   b'three'
-    for word in db.values(b"2"):
-        print(word)
-
-    del db[b"2"]
-
-    # No longer true, prints False
-    print(b"2" in db)
-
-    # Prints:
-    #  b"1"
-    #  b"3"
-    for key in db:
-        print(key)
-
-    db.close()
-
-    # Don't forget to close the underlying stream!
-    f.close()
-
-
-Functions
----------
-
-.. function:: open(stream, *, flags=0, pagesize=0, cachesize=0, minkeypage=0)
-
-   Open a database from a random-access `stream` (like an open file). All
-   other parameters are optional and keyword-only, and allow to tweak advanced
-   parameters of the database operation (most users will not need them):
-
-   * *flags* - Currently unused.
-   * *pagesize* - Page size used for the nodes in BTree. Acceptable range
-     is 512-65536. If 0, a port-specific default will be used, optimized for
-     port's memory usage and/or performance.
-   * *cachesize* - Suggested memory cache size in bytes. For a
-     board with enough memory using larger values may improve performance.
-     Cache policy is as follows: entire cache is not allocated at once;
-     instead, accessing a new page in database will allocate a memory buffer
-     for it, until value specified by *cachesize* is reached. Then, these
-     buffers will be managed using LRU (least recently used) policy. More
-     buffers may still be allocated if needed (e.g., if a database contains
-     big keys and/or values). Allocated cache buffers aren't reclaimed.
-   * *minkeypage* - Minimum number of keys to store per page. Default value
-     of 0 equivalent to 2.
-
-   Returns a BTree object, which implements a dictionary protocol (set
-   of methods), and some additional methods described below.
-
-Methods
--------
-
-.. method:: btree.close()
-
-   Close the database. It's mandatory to close the database at the end of
-   processing, as some unwritten data may be still in the cache. Note that
-   this does not close underlying stream with which the database was opened,
-   it should be closed separately (which is also mandatory to make sure that
-   data flushed from buffer to the underlying storage).
-
-.. method:: btree.flush()
-
-   Flush any data in cache to the underlying stream.
-
-.. method:: btree.__getitem__(key)
-            btree.get(key, default=None, /)
-            btree.__setitem__(key, val)
-            btree.__delitem__(key)
-            btree.__contains__(key)
-
-   Standard dictionary methods.
-
-.. method:: btree.__iter__()
-
-   A BTree object can be iterated over directly (similar to a dictionary)
-   to get access to all keys in order.
-
-.. method:: btree.keys([start_key, [end_key, [flags]]])
-            btree.values([start_key, [end_key, [flags]]])
-            btree.items([start_key, [end_key, [flags]]])
-
-   These methods are similar to standard dictionary methods, but also can
-   take optional parameters to iterate over a key sub-range, instead of
-   the entire database. Note that for all 3 methods, *start_key* and
-   *end_key* arguments represent key values. For example, `values()`
-   method will iterate over values corresponding to they key range
-   given. None values for *start_key* means "from the first key", no
-   *end_key* or its value of None means "until the end of database".
-   By default, range is inclusive of *start_key* and exclusive of
-   *end_key*, you can include *end_key* in iteration by passing *flags*
-   of `btree.INCL`. You can iterate in descending key direction
-   by passing *flags* of `btree.DESC`. The flags values can be ORed
-   together.
-
-Constants
----------
-
-.. data:: INCL
-
-   A flag for `keys()`, `values()`, `items()` methods to specify that
-   scanning should be inclusive of the end key.
-
-.. data:: DESC
-
-   A flag for `keys()`, `values()`, `items()` methods to specify that
-   scanning should be in descending direction of keys.

docs/library/framebuf.rst

@@ -1,170 +0,0 @@
-:mod:`framebuf` --- frame buffer manipulation
-=============================================
-
-.. include:: ../templates/unsupported_in_circuitpython.inc
-
-.. module:: framebuf
-   :synopsis: Frame buffer manipulation
-
-This module provides a general frame buffer which can be used to create
-bitmap images, which can then be sent to a display.
-
-class FrameBuffer
------------------
-
-The FrameBuffer class provides a pixel buffer which can be drawn upon with
-pixels, lines, rectangles, text and even other FrameBuffer's. It is useful
-when generating output for displays.
-
-For example::
-
-    import framebuf
-
-    # FrameBuffer needs 2 bytes for every RGB565 pixel
-    fbuf = framebuf.FrameBuffer(bytearray(100 * 10 * 2), 100, 10, framebuf.RGB565)
-
-    fbuf.fill(0)
-    fbuf.text('MicroPython!', 0, 0, 0xffff)
-    fbuf.hline(0, 9, 96, 0xffff)
-
-Constructors
-------------
-
-.. class:: FrameBuffer(buffer, width, height, format, stride=width, /)
-
-    Construct a FrameBuffer object.  The parameters are:
-
-        - *buffer* is an object with a buffer protocol which must be large
-          enough to contain every pixel defined by the width, height and
-          format of the FrameBuffer.
-        - *width* is the width of the FrameBuffer in pixels
-        - *height* is the height of the FrameBuffer in pixels
-        - *format* specifies the type of pixel used in the FrameBuffer;
-          permissible values are listed under Constants below. These set the
-          number of bits used to encode a color value and the layout of these
-          bits in *buffer*.
-          Where a color value c is passed to a method, c is a small integer
-          with an encoding that is dependent on the format of the FrameBuffer.
-        - *stride* is the number of pixels between each horizontal line
-          of pixels in the FrameBuffer. This defaults to *width* but may
-          need adjustments when implementing a FrameBuffer within another
-          larger FrameBuffer or screen. The *buffer* size must accommodate
-          an increased step size.
-
-    One must specify valid *buffer*, *width*, *height*, *format* and
-    optionally *stride*.  Invalid *buffer* size or dimensions may lead to
-    unexpected errors.
-
-Drawing primitive shapes
-------------------------
-
-The following methods draw shapes onto the FrameBuffer.
-
-.. method:: FrameBuffer.fill(c)
-
-    Fill the entire FrameBuffer with the specified color.
-
-.. method:: FrameBuffer.pixel(x, y[, c])
-
-    If *c* is not given, get the color value of the specified pixel.
-    If *c* is given, set the specified pixel to the given color.
-
-.. method:: FrameBuffer.hline(x, y, w, c)
-.. method:: FrameBuffer.vline(x, y, h, c)
-.. method:: FrameBuffer.line(x1, y1, x2, y2, c)
-
-    Draw a line from a set of coordinates using the given color and
-    a thickness of 1 pixel. The `line` method draws the line up to
-    a second set of coordinates whereas the `hline` and `vline`
-    methods draw horizontal and vertical lines respectively up to
-    a given length.
-
-.. method:: FrameBuffer.rect(x, y, w, h, c)
-.. method:: FrameBuffer.fill_rect(x, y, w, h, c)
-
-    Draw a rectangle at the given location, size and color. The `rect`
-    method draws only a 1 pixel outline whereas the `fill_rect` method
-    draws both the outline and interior.
-
-Drawing text
-------------
-
-.. method:: FrameBuffer.text(s, x, y[, c])
-
-    Write text to the FrameBuffer using the the coordinates as the upper-left
-    corner of the text. The color of the text can be defined by the optional
-    argument but is otherwise a default value of 1. All characters have
-    dimensions of 8x8 pixels and there is currently no way to change the font.
-
-
-Other methods
--------------
-
-.. method:: FrameBuffer.scroll(xstep, ystep)
-
-    Shift the contents of the FrameBuffer by the given vector. This may
-    leave a footprint of the previous colors in the FrameBuffer.
-
-.. method:: FrameBuffer.blit(fbuf, x, y, key=-1, palette=None)
-
-    Draw another FrameBuffer on top of the current one at the given coordinates.
-    If *key* is specified then it should be a color integer and the
-    corresponding color will be considered transparent: all pixels with that
-    color value will not be drawn.
-
-    The *palette* argument enables blitting between FrameBuffers with differing
-    formats. Typical usage is to render a monochrome or grayscale glyph/icon to
-    a color display. The *palette* is a FrameBuffer instance whose format is
-    that of the current FrameBuffer. The *palette* height is one pixel and its
-    pixel width is the number of colors in the source FrameBuffer. The *palette*
-    for an N-bit source needs 2**N pixels; the *palette* for a monochrome source
-    would have 2 pixels representing background and foreground colors. The
-    application assigns a color to each pixel in the *palette*. The color of the
-    current pixel will be that of that *palette* pixel whose x position is the
-    color of the corresponding source pixel.
-
-Constants
----------
-
-.. data:: framebuf.MONO_VLSB
-
-    Monochrome (1-bit) color format
-    This defines a mapping where the bits in a byte are vertically mapped with
-    bit 0 being nearest the top of the screen. Consequently each byte occupies
-    8 vertical pixels. Subsequent bytes appear at successive horizontal
-    locations until the rightmost edge is reached. Further bytes are rendered
-    at locations starting at the leftmost edge, 8 pixels lower.
-
-.. data:: framebuf.MONO_HLSB
-
-    Monochrome (1-bit) color format
-    This defines a mapping where the bits in a byte are horizontally mapped.
-    Each byte occupies 8 horizontal pixels with bit 7 being the leftmost.
-    Subsequent bytes appear at successive horizontal locations until the
-    rightmost edge is reached. Further bytes are rendered on the next row, one
-    pixel lower.
-
-.. data:: framebuf.MONO_HMSB
-
-    Monochrome (1-bit) color format
-    This defines a mapping where the bits in a byte are horizontally mapped.
-    Each byte occupies 8 horizontal pixels with bit 0 being the leftmost.
-    Subsequent bytes appear at successive horizontal locations until the
-    rightmost edge is reached. Further bytes are rendered on the next row, one
-    pixel lower.
-
-.. data:: framebuf.RGB565
-
-    Red Green Blue (16-bit, 5+6+5) color format
-
-.. data:: framebuf.GS2_HMSB
-
-    Grayscale (2-bit) color format
-
-.. data:: framebuf.GS4_HMSB
-
-    Grayscale (4-bit) color format
-
-.. data:: framebuf.GS8
-
-    Grayscale (8-bit) color format

docs/library/index.rst

@@ -1,15 +1,13 @@
 .. _micropython_lib:
 
-MicroPython libraries
+Standard Libraries
-=====================
+==================
 
-Python standard libraries and micro-libraries
+Python standard libraries
----------------------------------------------
+-------------------------
 
-The libraries below are inherited from MicroPython.
+The libraries below implement a subset of the corresponding
-They are similar to the standard Python libraries with the same name.
+standard Python (CPython) library. They are implemented in C, not Python.
-They implement a subset of or a variant of the corresponding
-standard Python library.
 
 CircuitPython's long-term goal is that code written in CircuitPython
 using Python standard libraries will be runnable on CPython without changes.
@@ -38,10 +36,22 @@ These libraries are not currently enabled in any CircuitPython build, but may be
    ctypes.rst
    select.rst
 
-Omitted functions in the ``string`` library
+Omitted ``string`` functions
--------------------------------------------
+----------------------------
 
 A few string operations are not enabled on small builds
 due to limited flash memory:
 ``string.center()``, ``string.partition()``, ``string.splitlines()``,
 ``string.reversed()``.
+
+
+CircuitPython/MicroPython-specific libraries
+--------------------------------------------
+
+Functionality specific to the CircuitPython/MicroPython implementations is available in
+the following libraries.
+
+.. toctree::
+   :maxdepth: 1
+
+   micropython.rst