Merge pull request #6391 from tekktrik/doc/add-additional-builtins-docs

dhalbert · web-flow · commit 951eea774863 · 2022-05-13T15:59:39.000-04:00
Add additional documentation for modules, builtin exceptions
diff --git a/docs/library/builtins.rst b/docs/library/builtins.rst
@@ -4,11 +4,18 @@
 All builtin functions and exceptions are described here. They are also
 available via ``builtins`` module.
 
+For more information about built-ins, see the following CPython documentation:
+
+* `Builtin CPython Functions <https://docs.python.org/3/library/functions.html>`_
+* `Builtin CPython Exceptions <https://docs.python.org/3/library/exceptions.html>`_
+* `Builtin CPython Constants <https://docs.python.org/3/library/constants.html>`_
+
+.. note:: Not all of these functions, types, exceptions, and constants are turned
+    on in all CircuitPython ports, for space reasons.
+
 Functions and types
 -------------------
 
-Not all of these functions and types are turned on in all CircuitPython ports, for space reasons.
-
 .. function:: abs()
 
 .. function:: all()
@@ -160,46 +167,77 @@ Not all of these functions and types are turned on in all CircuitPython ports, f
 Exceptions
 ----------
 
+.. exception:: ArithmeticError
+
 .. exception:: AssertionError
 
 .. exception:: AttributeError
 
+.. exception:: BaseException
+
+.. exception:: BrokenPipeError
+
+.. exception:: ConnectionError
+
+.. exception:: EOFError
+
 .. exception:: Exception
 
 .. exception:: ImportError
 
+.. exception:: IndentationError
+
 .. exception:: IndexError
 
 .. exception:: KeyboardInterrupt
 
 .. exception:: KeyError
 
+.. exception:: LookupError
+
 .. exception:: MemoryError
 
+.. exception:: MpyError
+
+    Not a part of the CPython standard library
+
 .. exception:: NameError
 
 .. exception:: NotImplementedError
 
 .. exception:: OSError
 
+.. exception:: OverflowError
+
 .. exception:: RuntimeError
 
 .. exception:: ReloadException
 
    `ReloadException` is used internally to deal with soft restarts.
 
+   Not a part of the CPython standard library
+
+.. exception:: StopAsyncIteration
+
 .. exception:: StopIteration
 
 .. exception:: SyntaxError
 
 .. exception:: SystemExit
 
-    |see_cpython| :py:class:`cpython:SystemExit`.
+.. exception:: TimeoutError
 
 .. exception:: TypeError
 
-    |see_cpython| :py:class:`cpython:TypeError`.
+.. exception:: UnicodeError
 
 .. exception:: ValueError
 
 .. exception:: ZeroDivisionError
+
+Constants
+---------
+
+.. data:: Ellipsis
+
+.. data:: NotImplemented
diff --git a/ports/raspberrypi/bindings/rp2pio/__init__.c b/ports/raspberrypi/bindings/rp2pio/__init__.c
@@ -30,7 +30,14 @@
 #include "bindings/rp2pio/StateMachine.h"
 #include "bindings/rp2pio/__init__.h"
 
-//| """Hardware interface to RP2 series' programmable IO (PIO) peripheral."""
+//| """Hardware interface to RP2 series' programmable IO (PIO) peripheral.
+//|
+//| .. note:: This module is intended to be used with the `adafruit_pioasm library
+//|     <https://github.com/adafruit/Adafruit_CircuitPython_PIOASM>`_.  For an
+//|     introduction and guide to working with PIO in CircuitPython, see `this
+//|     Learn guide <https://learn.adafruit.com/intro-to-rp2040-pio-with-circuitpython>`_.
+//|
+//| """
 //|
 
 //| def pins_are_sequential(pins: List[microcontroller.Pin]) -> bool:
diff --git a/shared-bindings/alarm/__init__.c b/shared-bindings/alarm/__init__.c
@@ -55,6 +55,9 @@
 //|
 //| For both light sleep and deep sleep, if CircuitPython is connected to a host computer,
 //| maintaining the connection takes priority and power consumption may not be reduced.
+//|
+//| For more information about working with alarms and light/deep sleep in CircuitPython,
+//| see `this Learn guide <https://learn.adafruit.com/deep-sleep-with-circuitpython>`_.
 //| """
 
 //| sleep_memory: SleepMemory
diff --git a/shared-bindings/analogio/__init__.c b/shared-bindings/analogio/__init__.c
@@ -59,12 +59,11 @@
 //| :py:meth:`~analogio.AnalogIn.deinit` the hardware. The last step is optional
 //| because CircuitPython will do it automatically after the program finishes.
 //|
-//| For the essentials of `analogio`, see the CircuitPython Essentials
-//| Learn guide:
-//| https://learn.adafruit.com/circuitpython-essentials/circuitpython-analog-in
+//| For the essentials of `analogio`, see the `CircuitPython Essentials
+//| Learn guide <https://learn.adafruit.com/circuitpython-essentials/circuitpython-analog-in>`_
 //|
-//| For more information on using `analogio`, see this additional Learn guide:
-//| https://learn.adafruit.com/circuitpython-basics-analog-inputs-and-outputs
+//| For more information on using `analogio`, see `this additional Learn guide
+//| <https://learn.adafruit.com/circuitpython-basics-analog-inputs-and-outputs>`_
 //| """
 //|
 
diff --git a/shared-bindings/audiomp3/__init__.c b/shared-bindings/audiomp3/__init__.c
@@ -31,7 +31,12 @@
 
 #include "shared-bindings/audiomp3/MP3Decoder.h"
 
-//| """Support for MP3-compressed audio files"""
+//| """Support for MP3-compressed audio files
+//|
+//| For more infomration about working with MP3 files in CircuitPython,
+//| see `this CircuitPython Essentials Learn guide page
+//| <https://learn.adafruit.com/circuitpython-essentials/circuitpython-mp3-audio>`_.
+//| """
 //|
 
 STATIC const mp_rom_map_elem_t audiomp3_module_globals_table[] = {
diff --git a/shared-bindings/bitmaptools/__init__.c b/shared-bindings/bitmaptools/__init__.c
@@ -43,7 +43,13 @@
 #include "extmod/vfs_posix.h"
 #endif
 
-//| """Collection of bitmap manipulation tools"""
+//| """Collection of bitmap manipulation tools
+//|
+//| .. note:: If you're looking for information about displaying bitmaps on
+//|     screens in CircuitPython, see `this Learn guide
+//|     <https://learn.adafruit.com/circuitpython-display-support-using-displayio>`_
+//|     for information about using the :py:mod:`displayio` module.
+//| """
 //|
 
 STATIC int16_t validate_point(mp_obj_t point, int16_t default_value) {
diff --git a/shared-bindings/board/__init__.c b/shared-bindings/board/__init__.c
@@ -47,9 +47,9 @@
 //| the default pins and settings.  For more information about serial communcication
 //| in CircuitPython, see the :mod:`busio`.
 //|
-//| For more information regarding the typical usage of :py:mod:`board`, refer to the CircuitPython
-//| Essentials Learn guide:
-//| https://learn.adafruit.com/circuitpython-essentials/circuitpython-pins-and-modules
+//| For more information regarding the typical usage of :py:mod:`board`, refer to the `CircuitPython
+//| Essentials Learn guide
+//| <https://learn.adafruit.com/circuitpython-essentials/circuitpython-pins-and-modules>`_
 //|
 //| .. warning:: The board module varies by board. The APIs documented here may or may not be
 //|              available on a specific board."""
diff --git a/shared-bindings/digitalio/__init__.c b/shared-bindings/digitalio/__init__.c
@@ -73,12 +73,11 @@
 //|       led.value = False
 //|       time.sleep(0.1)
 //|
-//| For the essentials of `digitalio`, see the CircuitPython Essentials
-//| Learn guide:
-//| https://learn.adafruit.com/circuitpython-essentials/circuitpython-digital-in-out
+//| For the essentials of `digitalio`, see the `CircuitPython Essentials
+//| Learn guide <https://learn.adafruit.com/circuitpython-essentials/circuitpython-digital-in-out>`_
 //|
-//| For more information on using `digitalio`, see this additional Learn guide:
-//| https://learn.adafruit.com/circuitpython-digital-inputs-and-outputs
+//| For more information on using `digitalio`, see `this additional Learn guide
+//| <https://learn.adafruit.com/circuitpython-digital-inputs-and-outputs>`_
 //| """
 
 STATIC const mp_rom_map_elem_t digitalio_module_globals_table[] = {
diff --git a/shared-bindings/displayio/__init__.c b/shared-bindings/displayio/__init__.c
@@ -51,9 +51,9 @@
 //| The `displayio` module contains classes to manage display output
 //| including synchronizing with refresh rates and partial updating.
 //|
-//| For more a more thorugh explanation and guide for using `displayio`, please
-//| refer to this Learn guide:
-//| https://learn.adafruit.com/circuitpython-display-support-using-displayio
+//| For more a more thorough explanation and guide for using `displayio`, please
+//| refer to `this Learn guide
+//| <https://learn.adafruit.com/circuitpython-display-support-using-displayio>`_.
 //| """
 //|
 
diff --git a/shared-bindings/fontio/__init__.c b/shared-bindings/fontio/__init__.c
@@ -33,7 +33,15 @@
 #include "shared-bindings/fontio/BuiltinFont.h"
 #include "shared-bindings/fontio/Glyph.h"
 
-//| """Core font related data structures"""
+//| """Core font related data structures
+//|
+//| .. note:: This module is intended only for low-level usage.  For working with
+//|     fonts in CircuitPython see the `adafruit_bitmap_font library
+//|     <https://github.com/adafruit/Adafruit_CircuitPython_Bitmap_Font>`_.
+//|     For information on creating custom fonts for use in CircuitPython, see
+//|     `this Learn guide <https://learn.adafruit.com/custom-fonts-for-pyportal-circuitpython-display>`_
+//|
+//| """
 //|
 
 STATIC const mp_rom_map_elem_t fontio_module_globals_table[] = {
diff --git a/shared-bindings/microcontroller/__init__.c b/shared-bindings/microcontroller/__init__.c
@@ -43,8 +43,9 @@
 
 //| """Pin references and cpu functionality
 //|
-//| The `microcontroller` module defines the pins from the perspective of the
-//| microcontroller. See :py:mod:`board` for board-specific pin mappings."""
+//| The `microcontroller` module defines the pins and other bare-metal hardware
+//| from the perspective of the microcontroller. See :py:mod:`board` for
+//| board-specific pin mappings."""
 //|
 //| from nvm import ByteArray
 //| from watchdog import WatchDogTimer
diff --git a/shared-bindings/neopixel_write/__init__.c b/shared-bindings/neopixel_write/__init__.c
@@ -95,13 +95,13 @@ STATIC void check_for_deinit(digitalio_digitalinout_obj_t *self) {
 //|
 //| .. note::
 //|
-//|     This library is typically not used by user level code.
+//|     This module is typically not used by user level code.
 //|
-//|     For more information on actually using NeoPixels, refer to the CircuitPython
-//|     Essentials Learn guide: https://learn.adafruit.com/circuitpython-essentials/circuitpython-neopixel
+//|     For more information on actually using NeoPixels, refer to the `CircuitPython
+//|     Essentials Learn guide <https://learn.adafruit.com/circuitpython-essentials/circuitpython-neopixel>`_
 //|
-//|     For a much more thorough guide about using NeoPixels, refer to the Adadfruit NeoPixel Überguide:
-//|     https://learn.adafruit.com/adafruit-neopixel-uberguide
+//|     For a much more thorough guide about using NeoPixels, refer to the `Adafruit NeoPixel Überguide
+//|     <https://learn.adafruit.com/adafruit-neopixel-uberguide>`_.
 //|
 //| """
 //|
diff --git a/shared-bindings/pwmio/__init__.c b/shared-bindings/pwmio/__init__.c
@@ -59,9 +59,8 @@
 //| hardware after program completion. Use ``deinit()`` or a ``with`` statement
 //| to do it yourself.
 //|
-//| For the essentials of `pwmio`, see the CircuitPython Essentials
-//| Learn guide:
-//| https://learn.adafruit.com/circuitpython-essentials/circuitpython-pwm
+//| For the essentials of `pwmio`, see the `CircuitPython Essentials
+//| Learn guide <https://learn.adafruit.com/circuitpython-essentials/circuitpython-pwm>`_.
 //| """
 //|
 
diff --git a/shared-bindings/qrio/__init__.c b/shared-bindings/qrio/__init__.c
@@ -31,9 +31,15 @@
 #include "py/obj.h"
 #include "py/enum.h"
 
-//| """`qrio` module.
+//| """Low-level QR code decoding
 //|
-//| Provides the `QRDecoder` object."""
+//| Provides the `QRDecoder` object used for decoding QR codes.  For more
+//| information about working with QR codes, see
+//| `this Learn guide <https://learn.adafruit.com/scan-qr-codes-with-circuitpython>`_.
+//|
+//| .. note:: This module only handles decoding QR codes.  If you are looking
+//|     to generate a QR code, use the
+//|     `adafruit_miniqr library <https://github.com/adafruit/Adafruit_CircuitPython_miniQR>`_"""
 //|
 
 STATIC const mp_rom_map_elem_t qrio_module_globals_table[] = {
diff --git a/shared-bindings/storage/__init__.c b/shared-bindings/storage/__init__.c
@@ -42,9 +42,9 @@
 //| CircuitPython does not have an OS, so this module provides this functionality
 //| directly.
 
-//| For more information regarding using the `storage` module, refer to the CircuitPython
-//| Essentials Learn guide:
-//| https://learn.adafruit.com/circuitpython-essentials/circuitpython-storage
+//| For more information regarding using the `storage` module, refer to the `CircuitPython
+//| Essentials Learn guide
+//| <https://learn.adafruit.com/circuitpython-essentials/circuitpython-storage>`_.
 //| """
 //|
 
diff --git a/shared-bindings/terminalio/__init__.c b/shared-bindings/terminalio/__init__.c
@@ -38,7 +38,12 @@
 //| """Displays text in a TileGrid
 //|
 //| The `terminalio` module contains classes to display a character stream on a display. The built
-//| in font is available as ``terminalio.FONT``."""
+//| in font is available as ``terminalio.FONT``.
+//|
+//| .. note:: This module does not give access to the
+//|     `REPL <https://learn.adafruit.com/welcome-to-circuitpython/interacting-with-the-serial-console>`_.
+//|
+//| """
 //|
 //| FONT: fontio.BuiltinFont
 //| """The built in font"""
