docs/library/index.rst: Clarify module naming and purpose.

Adds section about extending built-in modules from Python.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>

2 files changed, 53 insertions, 51 deletions

diff --git a/docs/library/index.rst b/docs/library/index.rst
index 9af4fec056..c69050267a 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -7,47 +7,39 @@ MicroPython libraries
 
    Important summary of this section
 
-   * MicroPython implements a subset of Python functionality for each module.
-   * To ease extensibility, MicroPython versions of standard Python modules
-     usually have ``u`` ("micro") prefix.
-   * Any particular MicroPython variant or port may miss any feature/function
-     described in this general documentation (due to resource constraints or
-     other limitations).
-
+   * MicroPython provides built-in modules that mirror the functionality of the
+     Python standard library (e.g. :mod:`os`, :mod:`time`), as well as
+     MicroPython-specific modules (e.g. :mod:`bluetooth`, :mod:`machine`).
+   * Most standard library modules implement a subset of the functionality of
+     the equivalent Python module, and in a few cases provide some
+     MicroPython-specific extensions (e.g. :mod:`array`, :mod:`os`)
+   * Due to resource constraints or other limitations, some ports or firmware
+     versions may not include all the functionality documented here.
+   * To allow for extensibility, the built-in modules can be extended from
+     Python code loaded onto the device.
 
 This chapter describes modules (function and class libraries) which are built
-into MicroPython. There are a few categories of such modules:
-
-* Modules which implement a subset of standard Python functionality and are not
-  intended to be extended by the user.
-* Modules which implement a subset of Python functionality, with a provision
-  for extension by the user (via Python code).
-* Modules which implement MicroPython extensions to the Python standard libraries.
-* Modules specific to a particular :term:`MicroPython port` and thus not portable.
-
-Note about the availability of the modules and their contents: This documentation
-in general aspires to describe all modules and functions/classes which are
-implemented in MicroPython project. However, MicroPython is highly configurable, and
-each port to a particular board/embedded system makes available only a subset
-of MicroPython libraries. For officially supported ports, there is an effort
-to either filter out non-applicable items, or mark individual descriptions
-with "Availability:" clauses describing which ports provide a given feature.
-
-With that in mind, please still be warned that some functions/classes
-in a module (or even the entire module) described in this documentation **may be
-unavailable** in a particular build of MicroPython on a particular system. The
-best place to find general information of the availability/non-availability
-of a particular feature is the "General Information" section which contains
-information pertaining to a specific :term:`MicroPython port`.
+into MicroPython. This documentation in general aspires to describe all modules
+and functions/classes which are implemented in the MicroPython project.
+However, MicroPython is highly configurable, and each port to a particular
+board/embedded system may include only a subset of the available MicroPython
+libraries.
+
+With that in mind, please be warned that some functions/classes in a module (or
+even the entire module) described in this documentation **may be unavailable**
+in a particular build of MicroPython on a particular system. The best place to
+find general information of the availability/non-availability of a particular
+feature is the "General Information" section which contains information
+pertaining to a specific :term:`MicroPython port`.
 
 On some ports you are able to discover the available, built-in libraries that
-can be imported by entering the following at the REPL::
+can be imported by entering the following at the :term:`REPL`::
 
     help('modules')
 
 Beyond the built-in libraries described in this documentation, many more
 modules from the Python standard library, as well as further MicroPython
-extensions to it, can be found in `micropython-lib`.
+extensions to it, can be found in :term:`micropython-lib`.
 
 Python standard libraries and micro-libraries
 ---------------------------------------------
@@ -55,20 +47,7 @@ Python standard libraries and micro-libraries
 The following standard Python libraries have been "micro-ified" to fit in with
 the philosophy of MicroPython.  They provide the core functionality of that
 module and are intended to be a drop-in replacement for the standard Python
-library.  Some modules below use a standard Python name, but prefixed with "u",
-e.g. ``json`` instead of ``json``. This is to signify that such a module is
-micro-library, i.e. implements only a subset of CPython module functionality.
-By naming them differently, a user has a choice to write a Python-level module
-to extend functionality for better compatibility with CPython (indeed, this is
-what done by the `micropython-lib` project mentioned above).
-
-On some embedded platforms, where it may be cumbersome to add Python-level
-wrapper modules to achieve naming compatibility with CPython, micro-modules
-are available both by their u-name, and also by their non-u-name.  The
-non-u-name can be overridden by a file of that name in your library path (``sys.path``).
-For example, ``import json`` will first search for a file ``json.py`` (or package
-directory ``json``) and load that module if it is found.  If nothing is found,
-it will fallback to loading the built-in ``json`` module.
+library.
 
 .. toctree::
    :maxdepth: 1
@@ -131,7 +110,7 @@ To access platform-specific hardware use the appropriate library, e.g.
 
 
 Libraries specific to the pyboard
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following libraries are specific to the pyboard.
 
@@ -143,7 +122,7 @@ The following libraries are specific to the pyboard.
 
 
 Libraries specific to the WiPy
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following libraries and classes are specific to the WiPy.
 
@@ -156,7 +135,7 @@ The following libraries and classes are specific to the WiPy.
 
 
 Libraries specific to the ESP8266 and ESP32
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following libraries are specific to the ESP8266 and ESP32.
 
@@ -168,7 +147,7 @@ The following libraries are specific to the ESP8266 and ESP32.
 
 
 Libraries specific to the RP2040
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following libraries are specific to the RP2040, as used in the Raspberry Pi Pico.
 
@@ -178,7 +157,7 @@ The following libraries are specific to the RP2040, as used in the Raspberry Pi
   rp2.rst
 
 Libraries specific to Zephyr
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following libraries are specific to the Zephyr port.
 
@@ -186,3 +165,24 @@ The following libraries are specific to the Zephyr port.
   :maxdepth: 2
 
   zephyr.rst
+
+Extending built-in libraries from Python
+----------------------------------------
+
+In most cases, the above modules are actually named ``umodule`` rather than
+``module``, but MicroPython will alias any module prefixed with a ``u`` to the
+non-``u`` version. However a file (or :term:``frozen module``) named
+``module.py`` will take precedence over this alias.
+
+This allows the user to provide an extended implementation of a built-in library
+(perhaps to provide additional CPython compatibility). The user-provided module
+(in ``module.py``) can still use the built-in functionality by importing
+``umodule`` directly. This is used extensively in :term:`micropython-lib`. See
+:ref:`packages` for more information.
+
+This applies to both the Python standard libraries (e.g. ``os``, ``time``, etc),
+but also the MicroPython libraries too (e.g. ``machine``, ``bluetooth``, etc).
+The main exception is the port-specific libraries (``pyb``, ``esp``, etc).
+
+*Other than when you specifically want to force the use of the built-in module,
+we recommend always using ``import module`` rather than ``import umodule``.*
diff --git a/docs/reference/packages.rst b/docs/reference/packages.rst
index e9adfc176e..eb44992ed6 100644
--- a/docs/reference/packages.rst
+++ b/docs/reference/packages.rst
@@ -1,3 +1,5 @@
+.. _packages:
+
 Distribution packages, package management, and deploying applications
 =====================================================================