From 1e6d18c915ccea0b6a19ffec9710d33dd7e5f866 Mon Sep 17 00:00:00 2001 From: David Lechner Date: Wed, 3 Jun 2020 20:38:45 -0500 Subject: [PATCH] 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 | 2 +- docs/library/esp32.rst | 4 ++-- docs/library/index.rst | 4 ++-- docs/library/micropython.rst | 2 +- docs/library/network.WLAN.rst | 4 ++-- docs/library/network.rst | 2 +- docs/library/pyb.Flash.rst | 5 +++-- docs/library/uerrno.rst | 4 ++-- docs/library/uio.rst | 2 ++ docs/library/uos.rst | 4 ++-- docs/library/ure.rst | 10 +++++----- docs/library/usocket.rst | 20 ++++++++++---------- docs/library/ussl.rst | 2 +- docs/make.bat | 1 + docs/reference/packages.rst | 34 +++++++++++++++++----------------- docs/reference/pyboard.py.rst | 2 +- docs/templates/replace.inc | 2 +- 17 files changed, 54 insertions(+), 50 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index e9c128e900..05709617c3 100644 --- a/docs/Makefile +++ b/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) diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst index f3be3692e3..33b779a214 100644 --- a/docs/library/esp32.rst +++ b/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 diff --git a/docs/library/index.rst b/docs/library/index.rst index 7b1636ce61..952e67d43c 100644 --- a/docs/library/index.rst +++ b/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:: diff --git a/docs/library/micropython.rst b/docs/library/micropython.rst index ded52deb0d..7106a1a2ff 100644 --- a/docs/library/micropython.rst +++ b/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) diff --git a/docs/library/network.WLAN.rst b/docs/library/network.WLAN.rst index 46a27a8fe4..885a4460c5 100644 --- a/docs/library/network.WLAN.rst +++ b/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 diff --git a/docs/library/network.rst b/docs/library/network.rst index 01e6f61369..208c58f852 100644 --- a/docs/library/network.rst +++ b/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 ` +interface classes implemented by :term:`MicroPython ports ` 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. diff --git a/docs/library/pyb.Flash.rst b/docs/library/pyb.Flash.rst index 2d2f83da1c..13f2097871 100644 --- a/docs/library/pyb.Flash.rst +++ b/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 diff --git a/docs/library/uerrno.rst b/docs/library/uerrno.rst index e336eb5c5c..def01362f1 100644 --- a/docs/library/uerrno.rst +++ b/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: diff --git a/docs/library/uio.rst b/docs/library/uio.rst index 1a64b36582..dddb83a170 100644 --- a/docs/library/uio.rst +++ b/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 diff --git a/docs/library/uos.rst b/docs/library/uos.rst index c49b13a5f5..ad10d91297 100644 --- a/docs/library/uos.rst +++ b/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. diff --git a/docs/library/ure.rst b/docs/library/ure.rst index ca5f35b703..e94d286175 100644 --- a/docs/library/ure.rst +++ b/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`. diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index e3b9d279a0..bc4b4b6d5a 100644 --- a/docs/library/usocket.rst +++ b/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 -installed from `micropython-lib` (as in the case of `MicroPython Unix port`), +:term:`MicroPython port`, ``socket`` module can be builtin or need to be +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 --------- @@ -81,7 +81,7 @@ Functions .. function:: getaddrinfo(host, port, af=0, type=0, proto=0, flags=0, /) - Translate the host/port argument into a sequence of 5-tuples that contain all the + Translate the host/port argument into a sequence of 5-tuples that contain all the necessary arguments for creating a socket connected to that service. Arguments *af*, *type*, and *proto* (which have the same meaning as for the `socket()` function) can be used to filter which kind of addresses are returned. If a parameter is not @@ -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: @@ -185,7 +185,7 @@ Methods on the socket object will fail. The remote end will receive EOF indication if supported by protocol. - Sockets are automatically closed when they are garbage-collected, but it is recommended + Sockets are automatically closed when they are garbage-collected, but it is recommended to `close()` them explicitly as soon you finished working with them. .. method:: socket.bind(address) @@ -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:: diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst index be84dc0545..ffe146331c 100644 --- a/docs/library/ussl.rst +++ b/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:: diff --git a/docs/make.bat b/docs/make.bat index 44f9682790..c09487fb74 100644 --- a/docs/make.bat +++ b/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%" == "" ( diff --git a/docs/reference/packages.rst b/docs/reference/packages.rst index 43217493e5..2854df23a0 100644 --- a/docs/reference/packages.rst +++ b/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 - on a `MicroPython port` with networking capabilities (for example, +2. :term:`upip` package manager can be used to install a distribution package + 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 `. At the very least, -`upip` is available in the `MicroPython Unix port`. +:term:`MicroPython ports `. At the very least, +: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 ` without native networking +For :term:`MicroPython ports ` 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 `, the process +For the low-memory :term:`MicroPython ports `, 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. diff --git a/docs/reference/pyboard.py.rst b/docs/reference/pyboard.py.rst index d404c738f1..30230eebc3 100644 --- a/docs/reference/pyboard.py.rst +++ b/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 ------------------------------ diff --git a/docs/templates/replace.inc b/docs/templates/replace.inc index 319c53735f..14f1875eee 100644 --- a/docs/templates/replace.inc +++ b/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:*