docs/machine*: Use markup adhering to the latest docs conventions.

docs/library/machine.I2C.rst

@@ -37,16 +37,16 @@ Constructors
 
    Construct and return a new I2C object using the following parameters:
 
-      - `id` identifies the particular I2C peripheral.  The default
+      - *id* identifies a particular I2C peripheral.  The default
         value of -1 selects a software implementation of I2C which can
         work (in most cases) with arbitrary pins for SCL and SDA.
-        If `id` is -1 then `scl` and `sda` must be specified.  Other
-        allowed values for `id` depend on the particular port/board,
-        and specifying `scl` and `sda` may or may not be required or
+        If *id* is -1 then *scl* and *sda* must be specified.  Other
+        allowed values for *id* depend on the particular port/board,
+        and specifying *scl* and *sda* may or may not be required or
         allowed in this case.
-      - `scl` should be a pin object specifying the pin to use for SCL.
-      - `sda` should be a pin object specifying the pin to use for SDA.
-      - `freq` should be an integer which sets the maximum frequency
+      - *scl* should be a pin object specifying the pin to use for SCL.
+      - *sda* should be a pin object specifying the pin to use for SDA.
+      - *freq* should be an integer which sets the maximum frequency
         for SCL.
 
 General Methods
@@ -56,9 +56,9 @@ General Methods
 
   Initialise the I2C bus with the given arguments:
 
-     - `scl` is a pin object for the SCL line
-     - `sda` is a pin object for the SDA line
-     - `freq` is the SCL clock rate
+     - *scl* is a pin object for the SCL line
+     - *sda* is a pin object for the SDA line
+     - *freq* is the SCL clock rate
 
 .. method:: I2C.deinit()
 
@@ -93,9 +93,9 @@ control over the bus, otherwise the standard methods (see below) can be used.
 
 .. method:: I2C.readinto(buf, nack=True)
 
-   Reads bytes from the bus and stores them into `buf`.  The number of bytes
-   read is the length of `buf`.  An ACK will be sent on the bus after
-   receiving all but the last byte.  After the last byte is received, if `nack`
+   Reads bytes from the bus and stores them into *buf*.  The number of bytes
+   read is the length of *buf*.  An ACK will be sent on the bus after
+   receiving all but the last byte.  After the last byte is received, if *nack*
    is true then a NACK will be sent, otherwise an ACK will be sent (and in this
    case the slave assumes more bytes are going to be read in a later call).
 
@@ -103,7 +103,7 @@ control over the bus, otherwise the standard methods (see below) can be used.
 
 .. method:: I2C.write(buf)
 
-   Write the bytes from `buf` to the bus.  Checks that an ACK is received
+   Write the bytes from *buf* to the bus.  Checks that an ACK is received
    after each byte and stops transmitting the remaining bytes if a NACK is
    received.  The function returns the number of ACKs that were received.
 
@@ -117,23 +117,23 @@ operations that target a given slave device.
 
 .. method:: I2C.readfrom(addr, nbytes, stop=True)
 
-   Read `nbytes` from the slave specified by `addr`.
-   If `stop` is true then a STOP condition is generated at the end of the transfer.
+   Read *nbytes* from the slave specified by *addr*.
+   If *stop* is true then a STOP condition is generated at the end of the transfer.
    Returns a `bytes` object with the data read.
 
 .. method:: I2C.readfrom_into(addr, buf, stop=True)
 
-   Read into `buf` from the slave specified by `addr`.
-   The number of bytes read will be the length of `buf`.
-   If `stop` is true then a STOP condition is generated at the end of the transfer.
+   Read into *buf* from the slave specified by *addr*.
+   The number of bytes read will be the length of *buf*.
+   If *stop* is true then a STOP condition is generated at the end of the transfer.
 
-   The method returns `None`.
+   The method returns ``None``.
 
 .. method:: I2C.writeto(addr, buf, stop=True)
 
-   Write the bytes from `buf` to the slave specified by `addr`.  If a
-   NACK is received following the write of a byte from `buf` then the
-   remaining bytes are not sent.  If `stop` is true then a STOP condition is
+   Write the bytes from *buf* to the slave specified by *addr*.  If a
+   NACK is received following the write of a byte from *buf* then the
+   remaining bytes are not sent.  If *stop* is true then a STOP condition is
    generated at the end of the transfer, even if a NACK is received.
    The function returns the number of ACKs that were received.
 
@@ -147,26 +147,26 @@ methods are convenience functions to communicate with such devices.
 
 .. method:: I2C.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
 
-   Read `nbytes` from the slave specified by `addr` starting from the memory
-   address specified by `memaddr`.
-   The argument `addrsize` specifies the address size in bits.
+   Read *nbytes* from the slave specified by *addr* starting from the memory
+   address specified by *memaddr*.
+   The argument *addrsize* specifies the address size in bits.
    Returns a `bytes` object with the data read.
 
 .. method:: I2C.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
 
-   Read into `buf` from the slave specified by `addr` starting from the
-   memory address specified by `memaddr`.  The number of bytes read is the
-   length of `buf`.
-   The argument `addrsize` specifies the address size in bits (on ESP8266
+   Read into *buf* from the slave specified by *addr* starting from the
+   memory address specified by *memaddr*.  The number of bytes read is the
+   length of *buf*.
+   The argument *addrsize* specifies the address size in bits (on ESP8266
    this argument is not recognised and the address size is always 8 bits).
 
-   The method returns `None`.
+   The method returns ``None``.
 
 .. method:: I2C.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
 
-   Write `buf` to the slave specified by `addr` starting from the
-   memory address specified by `memaddr`.
-   The argument `addrsize` specifies the address size in bits (on ESP8266
+   Write *buf* to the slave specified by *addr* starting from the
+   memory address specified by *memaddr*.
+   The argument *addrsize* specifies the address size in bits (on ESP8266
    this argument is not recognised and the address size is always 8 bits).
 
-   The method returns `None`.
+   The method returns ``None``.

docs/library/machine.UART.rst

@@ -18,7 +18,7 @@ UART objects can be created and initialised using::
 
 Supported parameters differ on a board:
 
-Pyboard: Bits can be 7, 8 or 9. Stop can be 1 or 2. With `parity=None`,
+Pyboard: Bits can be 7, 8 or 9. Stop can be 1 or 2. With *parity=None*,
 only 8 and 9 bits are supported.  With parity enabled, only 7 and 8 bits
 are supported.
 

docs/library/machine.rst

@@ -13,7 +13,7 @@ damage.
 
 .. _machine_callbacks:
 
-A note of callbacks used by functions and class methods of ``machine`` module:
+A note of callbacks used by functions and class methods of :mod:`machine` module:
 all these callbacks should be considered as executing in an interrupt context.
 This is true for both physical devices with IDs >= 0 and "virtual" devices
 with negative IDs like -1 (these "virtual" devices are still thin shims on
@@ -38,14 +38,14 @@ Interrupt related functions
 
    Disable interrupt requests.
    Returns the previous IRQ state which should be considered an opaque value.
-   This return value should be passed to the ``enable_irq`` function to restore
-   interrupts to their original state, before ``disable_irq`` was called.
+   This return value should be passed to the `enable_irq()` function to restore
+   interrupts to their original state, before `disable_irq()` was called.
 
 .. function:: enable_irq(state)
 
    Re-enable interrupt requests.
-   The ``state`` parameter should be the value that was returned from the most
-   recent call to the ``disable_irq`` function.
+   The *state* parameter should be the value that was returned from the most
+   recent call to the `disable_irq()` function.
 
 Power related functions
 -----------------------
@@ -71,8 +71,8 @@ Power related functions
 
    Stops the CPU and all peripherals (including networking interfaces, if any). Execution
    is resumed from the main script, just as with a reset. The reset cause can be checked
-   to know that we are coming from ``machine.DEEPSLEEP``. For wake up to actually happen,
-   wake sources should be configured first, like ``Pin`` change or ``RTC`` timeout.
+   to know that we are coming from `machine.DEEPSLEEP`. For wake up to actually happen,
+   wake sources should be configured first, like `Pin` change or `RTC` timeout.
 
 .. only:: port_wipy
 
@@ -98,18 +98,18 @@ Miscellaneous functions
 
 .. function:: time_pulse_us(pin, pulse_level, timeout_us=1000000)
 
-   Time a pulse on the given `pin`, and return the duration of the pulse in
-   microseconds.  The `pulse_level` argument should be 0 to time a low pulse
+   Time a pulse on the given *pin*, and return the duration of the pulse in
+   microseconds.  The *pulse_level* argument should be 0 to time a low pulse
    or 1 to time a high pulse.
 
-   If the current input value of the pin is different to `pulse_level`,
-   the function first (*) waits until the pin input becomes equal to `pulse_level`,
-   then (**) times the duration that the pin is equal to `pulse_level`.
-   If the pin is already equal to `pulse_level` then timing starts straight away.
+   If the current input value of the pin is different to *pulse_level*,
+   the function first (*) waits until the pin input becomes equal to *pulse_level*,
+   then (**) times the duration that the pin is equal to *pulse_level*.
+   If the pin is already equal to *pulse_level* then timing starts straight away.
 
    The function will return -2 if there was timeout waiting for condition marked
    (*) above, and -1 if there was timeout during the main measurement, marked (**)
-   above. The timeout is the same for both cases and given by `timeout_us` (which
+   above. The timeout is the same for both cases and given by *timeout_us* (which
    is in microseconds).
 
 .. _machine_constants: