docs: Fix Sphinx 3.x warnings, and enable warnings-as-errors on build.

This enables warnings as errors and fixes all current errors, namely:

- reference to terms in the glossary must now be explicit (:term:)
- method overloads must not be declared as a separate method or must
  use :noindex:
- 2 cases where `` should have been used instead of `

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 PYTHON        = python3
-SPHINXOPTS    =
+SPHINXOPTS    = -W --keep-going
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build/$(MICROPY_PORT)

docs/library/esp32.rst

@@ -84,9 +84,9 @@ methods to enable over-the-air (OTA) updates.
     Returns a 6-tuple ``(type, subtype, addr, size, label, encrypted)``.
 
 .. method:: Partition.readblocks(block_num, buf)
-.. method:: Partition.readblocks(block_num, buf, offset)
+            Partition.readblocks(block_num, buf, offset)
 .. method:: Partition.writeblocks(block_num, buf)
-.. method:: Partition.writeblocks(block_num, buf, offset)
+            Partition.writeblocks(block_num, buf, offset)
 .. method:: Partition.ioctl(cmd, arg)
 
     These methods implement the simple and :ref:`extended

docs/library/index.rst

@@ -23,7 +23,7 @@ into MicroPython. There are a few categories of such modules:
 * 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 `MicroPython port` and thus not portable.
+* 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
@@ -38,7 +38,7 @@ 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 `MicroPython port`.
+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::

docs/library/micropython.rst

@@ -100,7 +100,7 @@ Functions
    unlocked.
 
    Note: `heap_locked()` is not enabled on most ports by default,
-   requires `MICROPY_PY_MICROPYTHON_HEAP_LOCKED`.
+   requires ``MICROPY_PY_MICROPYTHON_HEAP_LOCKED``.
 
 .. function:: kbd_intr(chr)
 

docs/library/network.WLAN.rst

@@ -101,7 +101,7 @@ Methods
     nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
 
 .. method:: WLAN.config('param')
-.. method:: WLAN.config(param=value, ...)
+            WLAN.config(param=value, ...)
 
    Get or set general network interface parameters. These methods allow to work
    with additional parameters beyond standard IP configuration (as dealt with by
@@ -117,7 +117,7 @@ Methods
     print(ap.config('channel'))
 
    Following are commonly supported parameters (availability of a specific parameter
-   depends on network technology type, driver, and `MicroPython port`).
+   depends on network technology type, driver, and :term:`MicroPython port`).
 
    =============  ===========
    Parameter      Description

docs/library/network.rst

@@ -39,7 +39,7 @@ Common network adapter interface
 ================================
 
 This section describes an (implied) abstract base class for all network
-interface classes implemented by `MicroPython ports <MicroPython port>`
+interface classes implemented by :term:`MicroPython ports <MicroPython port>`
 for different hardware. This means that MicroPython does not actually
 provide ``AbstractNIC`` class, but any actual NIC class, as described
 in the following sections, implements methods as described here.

docs/library/pyb.Flash.rst

@@ -26,6 +26,7 @@ Constructors
    This constructor is deprecated and will be removed in a future version of MicroPython.
 
 .. class:: pyb.Flash(\*, start=-1, len=-1)
+   :noindex:
 
    Create and return a block device that accesses the flash at the specified offset. The length defaults to the remaining size of the device.
 
@@ -35,9 +36,9 @@ Methods
 -------
 
 .. method:: Flash.readblocks(block_num, buf)
-.. method:: Flash.readblocks(block_num, buf, offset)
+            Flash.readblocks(block_num, buf, offset)
 .. method:: Flash.writeblocks(block_num, buf)
-.. method:: Flash.writeblocks(block_num, buf, offset)
+            Flash.writeblocks(block_num, buf, offset)
 .. method:: Flash.ioctl(cmd, arg)
 
     These methods implement the simple and :ref:`extended

docs/library/uerrno.rst

@@ -7,7 +7,7 @@
 |see_cpython_module| :mod:`python:errno`.
 
 This module provides access to symbolic error codes for `OSError` exception.
-A particular inventory of codes depends on `MicroPython port`.
+A particular inventory of codes depends on :term:`MicroPython port`.
 
 Constants
 ---------
@@ -16,7 +16,7 @@ Constants
 
     Error codes, based on ANSI C/POSIX standard. All error codes start with
     "E". As mentioned above, inventory of the codes depends on
-    `MicroPython port`. Errors are usually accessible as ``exc.args[0]``
+    :term:`MicroPython port`. Errors are usually accessible as ``exc.args[0]``
     where ``exc`` is an instance of `OSError`. Usage example::
 
         try:

docs/library/uio.rst

@@ -114,7 +114,9 @@ Classes
         Get the current contents of the underlying buffer which holds data.
 
 .. class:: StringIO(alloc_size)
+    :noindex:
 .. class:: BytesIO(alloc_size)
+    :noindex:
 
     Create an empty `StringIO`/`BytesIO` object, preallocated to hold up
     to *alloc_size* number of bytes. That means that writing that amount

docs/library/uos.rst

@@ -252,7 +252,7 @@ that the block device supports the extended interface.
     dependent on the specific block device.
 
     .. method:: readblocks(block_num, buf)
-    .. method:: readblocks(block_num, buf, offset)
+                readblocks(block_num, buf, offset)
 
         The first form reads aligned, multiples of blocks.
         Starting at the block given by the index *block_num*, read blocks from
@@ -267,7 +267,7 @@ that the block device supports the extended interface.
         The number of bytes to read is given by the length of *buf*.
 
     .. method:: writeblocks(block_num, buf)
-    .. method:: writeblocks(block_num, buf, offset)
+                writeblocks(block_num, buf, offset)
 
         The first form writes aligned, multiples of blocks, and requires that the
         blocks that are written to be first erased (if necessary) by this method.

docs/library/ure.rst

@@ -138,12 +138,12 @@ Functions
    If *count* is specified and non-zero then substitution will stop after
    this many substitutions are made.  The *flags* argument is ignored.
 
-   Note: availability of this function depends on `MicroPython port`.
+   Note: availability of this function depends on :term:`MicroPython port`.
 
 .. data:: DEBUG
 
    Flag value, display debug information about compiled expression.
-   (Availability depends on `MicroPython port`.)
+   (Availability depends on :term:`MicroPython port`.)
 
 
 .. _regex:
@@ -184,7 +184,7 @@ to the replacement function in `sub()`.
 
    Return a tuple containing all the substrings of the groups of the match.
 
-   Note: availability of this method depends on `MicroPython port`.
+   Note: availability of this method depends on :term:`MicroPython port`.
 
 .. method:: match.start([index])
             match.end([index])
@@ -193,10 +193,10 @@ to the replacement function in `sub()`.
    substring group that was matched.  *index* defaults to the entire
    group, otherwise it will select a group.
 
-   Note: availability of these methods depends on `MicroPython port`.
+   Note: availability of these methods depends on :term:`MicroPython port`.
 
 .. method:: match.span([index])
 
    Returns the 2-tuple ``(match.start(index), match.end(index))``.
 
-   Note: availability of this method depends on `MicroPython port`.
+   Note: availability of this method depends on :term:`MicroPython port`.

docs/library/usocket.rst

@@ -37,8 +37,8 @@ power) and portable way to work with addresses.
 However, ``socket`` module (note the difference with native MicroPython
 ``usocket`` module described here) provides CPython-compatible way to specify
 addresses using tuples, as described below. Note that depending on a
-`MicroPython port`, ``socket`` module can be builtin or need to be
+:term:`MicroPython port`, ``socket`` module can be builtin or need to be
-installed from `micropython-lib` (as in the case of `MicroPython Unix port`),
+installed from `micropython-lib` (as in the case of :term:`MicroPython Unix port`),
 and some ports still accept only numeric addresses in the tuple format,
 and require to use `getaddrinfo` function to resolve domain names.
 
@@ -61,7 +61,7 @@ Tuple address format for ``socket`` module:
   must be 0. *scopeid* is the interface scope identifier for link-local
   addresses. Note the domain names are not accepted as *ipv6_address*,
   they should be resolved first using `usocket.getaddrinfo()`. Availability
-  of IPv6 support depends on a `MicroPython port`.
+  of IPv6 support depends on a :term:`MicroPython port`.
 
 Functions
 ---------
@@ -141,7 +141,7 @@ Constants
 .. data:: AF_INET
           AF_INET6
 
-   Address family types. Availability depends on a particular `MicroPython port`.
+   Address family types. Availability depends on a particular :term:`MicroPython port`.
 
 .. data:: SOCK_STREAM
           SOCK_DGRAM
@@ -151,7 +151,7 @@ Constants
 .. data:: IPPROTO_UDP
           IPPROTO_TCP
 
-   IP protocol numbers. Availability depends on a particular `MicroPython port`.
+   IP protocol numbers. Availability depends on a particular :term:`MicroPython port`.
    Note that you don't need to specify these in a call to `usocket.socket()`,
    because `SOCK_STREAM` socket type automatically selects `IPPROTO_TCP`, and
    `SOCK_DGRAM` - `IPPROTO_UDP`. Thus, the only real use of these constants
@@ -160,12 +160,12 @@ Constants
 .. data:: usocket.SOL_*
 
    Socket option levels (an argument to `setsockopt()`). The exact
-   inventory depends on a `MicroPython port`.
+   inventory depends on a :term:`MicroPython port`.
 
 .. data:: usocket.SO_*
 
    Socket options (an argument to `setsockopt()`). The exact
-   inventory depends on a `MicroPython port`.
+   inventory depends on a :term:`MicroPython port`.
 
 Constants specific to WiPy:
 
@@ -259,7 +259,7 @@ Methods
    completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket
    is put in blocking mode.
 
-   Not every `MicroPython port` supports this method. A more portable and
+   Not every :term:`MicroPython port` supports this method. A more portable and
    generic solution is to use `uselect.poll` object. This allows to wait on
    multiple objects at the same time (and not just on sockets, but on generic
    `stream` objects which support polling). Example::

docs/library/ussl.rst

@@ -24,7 +24,7 @@ Functions
    :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.
+   :term:`MicroPython port`, some or all keyword arguments above may be not supported.
 
 .. warning::
 

docs/make.bat

@@ -6,6 +6,7 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set BUILDDIR=_build
+set SPHINXOPTS=-W --keep-going
 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
 set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (

docs/reference/packages.rst

@@ -14,8 +14,8 @@ packages:
 
 1. Python modules and packages are turned into distribution package
    archives, and published at the Python Package Index (PyPI).
-2. `upip` package manager can be used to install a distribution package
+2. :term:`upip` package manager can be used to install a distribution package
-   on a `MicroPython port` with networking capabilities (for example,
+   on a :term:`MicroPython port` with networking capabilities (for example,
    on the Unix port).
 3. For ports without networking capabilities, an "installation image"
    can be prepared on the Unix port, and transferred to a device by
@@ -51,14 +51,14 @@ even by the smallest devices.
 Besides the small compression dictionary size, MicroPython distribution
 packages also have other optimizations, like removing any files from
 the archive which aren't used by the installation process. In particular,
-`upip` package manager doesn't execute ``setup.py`` during installation
+:term:`upip` package manager doesn't execute ``setup.py`` during installation
 (see below), and thus that file is not included in the archive.
 
 At the same time, these optimizations make MicroPython distribution
-packages not compatible with `CPython`'s package manager, ``pip``.
+packages not compatible with :term:`CPython`'s package manager, ``pip``.
 This isn't considered a big problem, because:
 
-1. Packages can be installed with `upip`, and then can be used with
+1. Packages can be installed with :term:`upip`, and then can be used with
    CPython (if they are compatible with it).
 2. In the other direction, majority of CPython packages would be
    incompatible with MicroPython by various reasons, first of all,
@@ -73,12 +73,12 @@ resource constrained devices.
 ------------------------
 
 MicroPython distribution packages are intended to be installed using
-the `upip` package manager. `upip` is a Python application which is
+the :term:`upip` package manager. :term:`upip` is a Python application which is
 usually distributed (as frozen bytecode) with network-enabled
-`MicroPython ports <MicroPython port>`. At the very least,
+:term:`MicroPython ports <MicroPython port>`. At the very least,
-`upip` is available in the `MicroPython Unix port`.
+:term:`upip` is available in the :term:`MicroPython Unix port`.
 
-On any `MicroPython port` providing `upip`, it can be accessed as
+On any :term:`MicroPython port` providing :term:`upip`, it can be accessed as
 following::
 
     import upip
@@ -123,12 +123,12 @@ commands which corresponds to the example above are::
 Cross-installing packages
 -------------------------
 
-For `MicroPython ports <MicroPython port>` without native networking
+For :term:`MicroPython ports <MicroPython port>` without native networking
 capabilities, the recommend process is "cross-installing" them into a
-"directory image" using the `MicroPython Unix port`, and then
+"directory image" using the :term:`MicroPython Unix port`, and then
 transferring this image to a device by suitable means.
 
-Installing to a directory image involves using ``-p`` switch to `upip`::
+Installing to a directory image involves using ``-p`` switch to :term:`upip`::
 
     micropython -m upip install -p install_dir micropython-pystone_lowmem
 
@@ -137,13 +137,13 @@ packages) will be available in the ``install_dir/`` subdirectory. You
 would need to transfer contents of this directory (without the
 ``install_dir/`` prefix) to the device, at the suitable location, where
 it can be found by the Python ``import`` statement (see discussion of
-the `upip` installation path above).
+the :term:`upip` installation path above).
 
 
 Cross-installing packages with freezing
 ---------------------------------------
 
-For the low-memory `MicroPython ports <MicroPython port>`, the process
+For the low-memory :term:`MicroPython ports <MicroPython port>`, the process
 described in the previous section does not provide the most efficient
 resource usage,because the packages are installed in the source form,
 so need to be compiled to the bytecome on each import. This compilation
@@ -160,7 +160,7 @@ mentioned above:
 * Filesystem is not required for frozen packages.
 
 Using frozen bytecode requires building the executable (firmware)
-for a given `MicroPython port` from the C source code. Consequently,
+for a given :term:`MicroPython port` from the C source code. Consequently,
 the process is:
 
 1. Follow the instructions for a particular port on setting up a
@@ -168,7 +168,7 @@ the process is:
    study instructions in ``ports/esp8266/README.md`` and follow them.
    Make sure you can build the port and deploy the resulting
    executable/firmware successfully before proceeding to the next steps.
-2. Build `MicroPython Unix port` and make sure it is in your PATH and
+2. Build :term:`MicroPython Unix port` and make sure it is in your PATH and
    you can execute ``micropython``.
 3. Change to port's directory (e.g. ``ports/esp8266/`` for ESP8266).
 4. Run ``make clean-frozen``. This step cleans up any previous
@@ -281,7 +281,7 @@ following calls::
     pkg_resources.resource_stream(__name__, "data/page.html")
     pkg_resources.resource_stream(__name__, "data/image.png")
 
-You can develop and debug using the `MicroPython Unix port` as usual.
+You can develop and debug using the :term:`MicroPython Unix port` as usual.
 When time comes to make a distribution package out of it, just use
 overridden "sdist" command from sdist_upip.py module as described in
 the previous section.

docs/reference/pyboard.py.rst

@@ -68,7 +68,7 @@ example::
     $ pyboard.py -c 'print(1+1)'
 
 Similarly, the ``PYBOARD_BAUDRATE`` environment variable can be used
-to set the default for the `--baudrate` option.
+to set the default for the ``--baudrate`` option.
 
 Running a script on the device
 ------------------------------

docs/templates/replace.inc

@@ -4,6 +4,6 @@
 
 .. |see_cpython_module| replace::
 
-    *This module implements a subset of the corresponding* `CPython` *module,
+    *This module implements a subset of the corresponding* :term:`CPython` *module,
     as described below. For more information, refer to the original
     CPython documentation:*