Merge pull request #6353 from tekktrik/doc/add-communication-links

Add links to guides for "essential" modules, others

Author: dhalbert

shared-bindings/analogio/__init__.c

@@ -57,7 +57,15 @@
 //| This example will initialize the the device, read
 //| :py:data:`~analogio.AnalogIn.value` and then
 //| :py:meth:`~analogio.AnalogIn.deinit` the hardware. The last step is optional
-//| because CircuitPython will do it automatically after the program finishes."""
+//| 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 more information on using `analogio`, see this additional Learn guide:
+//| https://learn.adafruit.com/circuitpython-basics-analog-inputs-and-outputs
+//| """
 //|
 
 STATIC const mp_rom_map_elem_t analogio_module_globals_table[] = {

shared-bindings/board/__init__.c

@@ -43,6 +43,14 @@
 //| Common container for board base pin names. These will vary from board to
 //| board so don't expect portability when using this module.
 //|
+//| Another common use of this module is to use serial communciation buses with
+//| 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
+//|
 //| .. warning:: The board module varies by board. The APIs documented here may or may not be
 //|              available on a specific board."""
 

shared-bindings/busio/__init__.c

@@ -68,7 +68,19 @@
 //| This example will initialize the the device, run
 //| :py:meth:`~busio.I2C.scan` and then :py:meth:`~busio.I2C.deinit` the
 //| hardware. The last step is optional because CircuitPython automatically
-//| resets hardware after a program finishes."""
+//| resets hardware after a program finishes.
+//|
+//| Note that drivers will typically handle communication if provided the bus
+//| instance (such as ``busio.I2C(board.SCL, board.SDA)``), and that many of
+//| the methods listed here are lower level functionalities that are needed
+//| for working with custom drivers.
+//|
+//| Tutorial for I2C and SPI:
+//| https://learn.adafruit.com/circuitpython-basics-i2c-and-spi
+//|
+//| Tutorial for UART:
+//| https://learn.adafruit.com/circuitpython-essentials/circuitpython-uart-serial
+//| """
 //|
 
 STATIC const mp_rom_map_elem_t busio_module_globals_table[] = {

shared-bindings/digitalio/__init__.c

@@ -71,8 +71,15 @@
 //|       led.value = True
 //|       time.sleep(0.1)
 //|       led.value = False
-//|       time.sleep(0.1)"""
+//|       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 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[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_digitalio) },

shared-bindings/displayio/__init__.c

@@ -49,7 +49,12 @@
 //| """Native helpers for driving displays
 //|
 //| The `displayio` module contains classes to manage display output
-//| including synchronizing with refresh rates and partial updating."""
+//| 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
+//| """
 //|
 
 //| import paralleldisplay

shared-bindings/neopixel_write/__init__.c

@@ -91,7 +91,19 @@ STATIC void check_for_deinit(digitalio_digitalinout_obj_t *self) {
 //|   pin = digitalio.DigitalInOut(board.NEOPIXEL)
 //|   pin.direction = digitalio.Direction.OUTPUT
 //|   pixel_off = bytearray([0, 0, 0])
-//|   neopixel_write.neopixel_write(pin, pixel_off)"""
+//|   neopixel_write.neopixel_write(pin, pixel_off)
+//|
+//| .. note::
+//|
+//|     This library 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 a much more thorough guide about using NeoPixels, refer to the Adadfruit NeoPixel Überguide:
+//|     https://learn.adafruit.com/adafruit-neopixel-uberguide
+//|
+//| """
 //|
 //| def neopixel_write(digitalinout: digitalio.DigitalInOut, buf: ReadableBuffer) -> None:
 //|     """Write buf out on the given DigitalInOut.

shared-bindings/pwmio/__init__.c

@@ -57,7 +57,12 @@
 //| :py:data:`~pwmio.PWMOut.duty_cycle`, and then sleep 0.1 seconds.
 //| CircuitPython will automatically turn off the PWM when it resets all
 //| hardware after program completion. Use ``deinit()`` or a ``with`` statement
-//| to do it yourself."""
+//| to do it yourself.
+//|
+//| For the essentials of `pwmio`, see the CircuitPython Essentials
+//| Learn guide:
+//| https://learn.adafruit.com/circuitpython-essentials/circuitpython-pwm
+//| """
 //|
 
 STATIC const mp_rom_map_elem_t pwmio_module_globals_table[] = {

shared-bindings/storage/__init__.c

@@ -40,7 +40,12 @@
 //| The `storage` provides storage management functionality such as mounting and
 //| unmounting which is typically handled by the operating system hosting Python.
 //| CircuitPython does not have an OS, so this module provides this functionality
-//| directly."""
+//| directly.
+
+//| For more information regarding using the `storage` module, refer to the CircuitPython
+//| Essentials Learn guide:
+//| https://learn.adafruit.com/circuitpython-essentials/circuitpython-storage
+//| """
 //|
 
 //| def mount(filesystem: VfsFat, mount_path: str, *, readonly: bool = False) -> None: