docs: Fix some references and RST markup to eliminate Sphinx warnings.

dpgeorge · dpgeorge · commit 0db49c37a4e8 · 2018-03-15T15:50:51.000+11:00
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
