From 5de064fbd056944e393be9355855eee6562fecdb Mon Sep 17 00:00:00 2001
From: Paul Sokolovsky <pfalcon@users.sourceforge.net>
Date: Sat, 23 Dec 2017 21:21:08 +0200
Subject: [PATCH] docs/library/index: Elaborate uPy libraries intro.
---
docs/library/index.rst | 26 ++++++++++++++------------
1 file changed, 14 insertions(+), 12 deletions(-)
diff --git a/docs/library/index.rst b/docs/library/index.rst
index b141abf1e..af1a0ff69 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -9,34 +9,36 @@ MicroPython libraries
* MicroPython implements a subset of Python functionality for each module.
* To ease extensibility, MicroPython versions of standard Python modules
- usually have ``u`` (micro) prefix.
+ 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.
+ described in this general documentation (due to resource constraints or
+ other limitations).
This chapter describes modules (function and class libraries) which are built
-into MicroPython. There are a few categories of modules:
+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 port and thus not portable.
+* Modules specific to a particular `MicroPython port` and thus not portable.
-Note about the availability of modules and their contents: This documentation
+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. However, MicroPython is highly configurable, and
+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 board. The
+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 port.
+information pertaining to a specific `MicroPython port`.
Beyond the built-in libraries described in this documentation, many more
modules from the Python standard library, as well as further MicroPython
@@ -58,9 +60,9 @@ 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 package path.
-For example, ``import json`` will first search for a file ``json.py`` or
-directory ``json`` and load that package if it is found. If nothing is found,
+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 ``ujson`` module.
.. only:: port_unix
--
GitLab