diff --git a/docs/library/array.rst b/docs/library/array.rst index d096c6ec48..f837b03436 100644 --- a/docs/library/array.rst +++ b/docs/library/array.rst @@ -16,14 +16,14 @@ Classes .. class:: array.array(typecode, [iterable]) Create array with elements of given type. Initial contents of the - array are given by an `iterable`. If it is not provided, an empty + array are given by *iterable*. If it is not provided, an empty array is created. .. method:: append(val) - Append new element to the end of array, growing it. + Append new element *val* to the end of array, growing it. .. method:: extend(iterable) - Append new elements as contained in an iterable to the end of + Append new elements as contained in *iterable* to the end of array, growing it. diff --git a/docs/library/lcd160cr.rst b/docs/library/lcd160cr.rst index 567994640b..bb8e6da22c 100644 --- a/docs/library/lcd160cr.rst +++ b/docs/library/lcd160cr.rst @@ -172,7 +172,7 @@ Drawing text ------------ To draw text one sets the position, color and font, and then uses -`write` to draw the text. +`LCD160CR.write` to draw the text. .. method:: LCD160CR.set_pos(x, y) @@ -279,7 +279,7 @@ Touch screen methods .. method:: LCD160CR.is_touched() Returns a boolean: ``True`` if there is currently a touch force on the screen, - `False` otherwise. + ``False`` otherwise. .. method:: LCD160CR.get_touch() diff --git a/docs/library/pyb.Switch.rst b/docs/library/pyb.Switch.rst index e5ab6bd844..1edcbf8488 100644 --- a/docs/library/pyb.Switch.rst +++ b/docs/library/pyb.Switch.rst @@ -38,7 +38,7 @@ Methods .. method:: Switch.value() - Get the switch state. Returns `True` if pressed down, otherwise `False`. + Get the switch state. Returns ``True`` if pressed down, otherwise ``False``. .. method:: Switch.callback(fun) diff --git a/docs/library/uio.rst b/docs/library/uio.rst index 7e6c932284..81420702dc 100644 --- a/docs/library/uio.rst +++ b/docs/library/uio.rst @@ -81,7 +81,7 @@ Functions Open a file. Builtin ``open()`` function is aliased to this function. All ports (which provide access to file system) are required to support - `mode` parameter, but support for other arguments vary by port. + *mode* parameter, but support for other arguments vary by port. Classes ------- @@ -103,7 +103,7 @@ Classes text-mode I/O (similar to a normal file opened with "t" modifier). `BytesIO` is used for binary-mode I/O (similar to a normal file opened with "b" modifier). Initial contents of file-like objects - can be specified with `string` parameter (should be normal string + can be specified with *string* parameter (should be normal string for `StringIO` or bytes object for `BytesIO`). All the usual file methods like ``read()``, ``write()``, ``seek()``, ``flush()``, ``close()`` are available on these objects, and additionally, a diff --git a/docs/library/uselect.rst b/docs/library/uselect.rst index fb43f7e63e..77d4584731 100644 --- a/docs/library/uselect.rst +++ b/docs/library/uselect.rst @@ -35,10 +35,10 @@ Methods Register `stream` *obj* for polling. *eventmask* is logical OR of: - * `uselect.POLLIN` - data available for reading - * `uselect.POLLOUT` - more data can be written + * ``uselect.POLLIN`` - data available for reading + * ``uselect.POLLOUT`` - more data can be written - Note that flags like `uselect.POLLHUP` and `uselect.POLLERR` are + Note that flags like ``uselect.POLLHUP`` and ``uselect.POLLERR`` are *not* valid as input eventmask (these are unsolicited events which will be returned from `poll()` regardless of whether they are asked for). This semantics is per POSIX. @@ -63,7 +63,7 @@ Methods tuple, depending on a platform and version, so don't assume that its size is 2. The ``event`` element specifies which events happened with a stream and is a combination of ``uselect.POLL*`` constants described above. Note that - flags `uselect.POLLHUP` and `uselect.POLLERR` can be returned at any time + flags ``uselect.POLLHUP`` and ``uselect.POLLERR`` can be returned at any time (even if were not asked for), and must be acted on accordingly (the corresponding stream unregistered from poll and likely closed), because otherwise all further invocations of `poll()` may return immediately with diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst index 903a351f4d..be84dc0545 100644 --- a/docs/library/ussl.rst +++ b/docs/library/ussl.rst @@ -18,10 +18,10 @@ Functions Takes a `stream` *sock* (usually usocket.socket instance of ``SOCK_STREAM`` type), and returns an instance of ssl.SSLSocket, which wraps the underlying stream in an SSL context. Returned object has the usual `stream` interface methods like - `read()`, `write()`, etc. In MicroPython, the returned object does not expose - socket interface and methods like `recv()`, `send()`. In particular, a + ``read()``, ``write()``, etc. In MicroPython, the returned object does not expose + socket interface and methods like ``recv()``, ``send()``. In particular, a server-side SSL socket should be created from a normal socket returned from - `accept()` on a non-SSL listening server socket. + :meth:`~usocket.socket.accept()` on a non-SSL listening server socket. Depending on the underlying module implementation in a particular `MicroPython port`, some or all keyword arguments above may be not supported. diff --git a/docs/reference/constrained.rst b/docs/reference/constrained.rst index e7de459bc9..edac0ae681 100644 --- a/docs/reference/constrained.rst +++ b/docs/reference/constrained.rst @@ -185,7 +185,7 @@ a file it will save RAM if this is done in a piecemeal fashion. Rather than creating a large string object, create a substring and feed it to the stream before dealing with the next. -The best way to create dynamic strings is by means of the string `format` +The best way to create dynamic strings is by means of the string ``format()`` method: .. code:: @@ -259,7 +259,7 @@ were a string. **Runtime compiler execution** The Python funcitons `eval` and `exec` invoke the compiler at runtime, which -requires significant amounts of RAM. Note that the `pickle` library from +requires significant amounts of RAM. Note that the ``pickle`` library from `micropython-lib` employs `exec`. It may be more RAM efficient to use the `ujson` library for object serialisation. diff --git a/docs/reference/packages.rst b/docs/reference/packages.rst index e1609985a5..8be2461c2d 100644 --- a/docs/reference/packages.rst +++ b/docs/reference/packages.rst @@ -42,7 +42,7 @@ size, which means that to uncompress a compressed stream, 32KB of contguous memory needs to be allocated. This requirement may be not satisfiable on low-memory devices, which may have total memory available less than that amount, and even if not, a contiguous block like that -may be hard to allocate due to `memory fragmentation`. To accommodate +may be hard to allocate due to memory fragmentation. To accommodate these constraints, MicroPython distribution packages use Gzip compression with the dictionary size of 4K, which should be a suitable compromise with still achieving some compression while being able to uncompressed @@ -243,7 +243,7 @@ the data files as "resources", and abstracting away access to them. Python supports resource access using its "setuptools" library, using ``pkg_resources`` module. MicroPython, following its usual approach, implements subset of the functionality of that module, specifically -`pkg_resources.resource_stream(package, resource)` function. +``pkg_resources.resource_stream(package, resource)`` function. The idea is that an application calls this function, passing a resource identifier, which is a relative path to data file within the specified package (usually top-level application package). It diff --git a/docs/reference/speed_python.rst b/docs/reference/speed_python.rst index 279a1bbcdc..4db60ec14d 100644 --- a/docs/reference/speed_python.rst +++ b/docs/reference/speed_python.rst @@ -63,8 +63,8 @@ used for communication with a device. A typical driver will create the buffer in constructor and use it in its I/O methods which will be called repeatedly. The MicroPython libraries typically provide support for pre-allocated buffers. For -example, objects which support stream interface (e.g., file or UART) provide `read()` -method which allocates new buffer for read data, but also a `readinto()` method +example, objects which support stream interface (e.g., file or UART) provide ``read()`` +method which allocates new buffer for read data, but also a ``readinto()`` method to read data into an existing buffer. Floating Point @@ -109,10 +109,10 @@ the 10K buffer go (be ready for garbage collection), instead of making a long-living memoryview and keeping 10K blocked for GC. Nonetheless, `memoryview` is indispensable for advanced preallocated buffer -management. `readinto()` method discussed above puts data at the beginning +management. ``readinto()`` method discussed above puts data at the beginning of buffer and fills in entire buffer. What if you need to put data in the middle of existing buffer? Just create a memoryview into the needed section -of buffer and pass it to `readinto()`. +of buffer and pass it to ``readinto()``. Identifying the slowest section of code --------------------------------------- @@ -326,7 +326,7 @@ standard approach would be to write mypin.value(mypin.value() ^ 1) # mypin was instantiated as an output pin -This involves the overhead of two calls to the `Pin` instance's :meth:`~machine.Pin.value()` +This involves the overhead of two calls to the :class:`~machine.Pin` instance's :meth:`~machine.Pin.value()` method. This overhead can be eliminated by performing a read/write to the relevant bit of the chip's GPIO port output data register (odr). To facilitate this the ``stm`` module provides a set of constants providing the addresses of the relevant registers.