docs(api, docs): port Python API documentation to mkdocs

api/src/opentrons/execute.py

@@ -2,7 +2,7 @@
 
 This module has functions that can be imported to provide protocol
 contexts for running protocols during interactive sessions like Jupyter or just
-regular python shells. It also provides a console entrypoint for running a
+regular Python shells. It also provides a console entrypoint for running a
 protocol from the command line.
 """
 import asyncio
@@ -128,40 +128,43 @@ def get_protocol_api(
     # *
 ) -> protocol_api.ProtocolContext:
     """
-    Build and return a ``protocol_api.ProtocolContext``
+    Build and return a `protocol_api.ProtocolContext`
     connected to the robot.
 
     This can be used to run protocols from interactive Python sessions
     such as Jupyter or an interpreter on the command line:
 
-    .. code-block:: python
-
-        >>> from opentrons.execute import get_protocol_api
-        >>> protocol = get_protocol_api('2.0')
-        >>> instr = protocol.load_instrument('p300_single', 'right')
-        >>> instr.home()
+    ```python
+    from opentrons.execute import get_protocol_api
+    protocol = get_protocol_api('2.0')
+    instr = protocol.load_instrument('p300_single', 'right')
+    instr.home()
+    ```
 
     When this function is called, modules and instruments will be recached.
 
-    :param version: The API version to use. This must be lower than
-        ``opentrons.protocol_api.MAX_SUPPORTED_VERSION``.
-        It may be specified either as a string (``'2.0'``) or
-        as a ``protocols.types.APIVersion``
-        (``APIVersion(2, 0)``).
-    :param bundled_labware: If specified, a mapping from labware names to
-        labware definitions for labware to consider in the
-        protocol. Note that if you specify this, *only*
-        labware in this argument will be allowed in the
-        protocol. This is preparation for a beta feature
-        and is best not used.
-    :param bundled_data: If specified, a mapping from filenames to contents
-        for data to be available in the protocol from
-        :py:obj:`opentrons.protocol_api.ProtocolContext.bundled_data`.
-    :param extra_labware: A mapping from labware load names to custom labware definitions.
-        If this is ``None`` (the default), and this function is called on a robot,
-        it will look for labware in the ``labware`` subdirectory of the Jupyter
-        data directory.
-    :return: The protocol context.
+    Args:
+        version: The API version to use. This must be lower than
+            `opentrons.protocol_api.MAX_SUPPORTED_VERSION`.
+            It may be specified either as a string (`'2.0'`) or
+            as a [`APIVersion`][opentrons.protocols.api_support.types.APIVersion]
+            (`APIVersion(2, 0)`).
+        bundled_labware: If specified, a mapping from labware names to
+            labware definitions for labware to consider in the
+            protocol. Note that if you specify this, *only*
+            labware in this argument will be allowed in the
+            protocol. This is preparation for a beta feature
+            and is best not used.
+        bundled_data: If specified, a mapping from filenames to contents
+            for data to be available in the protocol from
+            [`bundled_data`][opentrons.protocol_api.ProtocolContext.bundled_data].
+        extra_labware: A mapping from labware load names to custom labware definitions.
+            If this is `None` (the default), and this function is called on a robot,
+            it will look for labware in the `labware` subdirectory of the Jupyter
+            data directory.
+
+    Returns:
+        The protocol context.
     """
     if isinstance(version, str):
         checked_version = parse.version_from_string(version)
@@ -212,13 +215,17 @@ def get_protocol_api(
 
 
 def get_arguments(parser: argparse.ArgumentParser) -> argparse.ArgumentParser:
-    """Get the argument parser for this module
+    """
+    Get the argument parser for this module.
 
     Useful if you want to use this module as a component of another CLI program
     and want to add its arguments.
 
-    :param parser: A parser to add arguments to.
-    :returns argparse.ArgumentParser: The parser with arguments added.
+    Args:
+        parser: A parser to add arguments to.
+
+    Returns:
+        argparse.ArgumentParser: The parser with arguments added.
     """
     parser.add_argument(
         "-l",
@@ -302,70 +309,72 @@ def execute(
     """
     Run the protocol itself.
 
-    This is a one-stop function to run a protocol, whether python or json,
-    no matter the api version, from external (i.e. not bound up in other
+    This is a one-stop function to run a protocol, whether Python or JSON,
+    no matter the API version, from external (i.e. not bound up in other
     internal server infrastructure) sources.
 
     To run an opentrons protocol from other places, pass in a file like
-    object as protocol_file; this function either returns (if the run has no
+    object as `protocol_file`; this function either returns (if the run has no
     problems) or raises an exception.
 
     To call from the command line use either the autogenerated entrypoint
-    ``opentrons_execute`` or ``python -m opentrons.execute``.
-
-    :param protocol_file: The protocol file to execute
-    :param protocol_name: The name of the protocol file. This is required
-        internally, but it may not be a thing we can get
-        from the ``protocol_file`` argument.
-    :param propagate_logs: Whether this function should allow logs from the
-        Opentrons stack to propagate up to the root handler.
-        This can be useful if you're integrating this
-        function in a larger application, but most logs that
-        occur during protocol simulation are best associated
-        with the actions in the protocol that cause them.
-        Default: ``False``
-    :param log_level: The level of logs to emit on the command line:
-        ``"debug"``, ``"info"``, ``"warning"``, or ``"error"``.
-        Defaults to ``"warning"``.
-    :param emit_runlog: A callback for printing the run log. If specified, this
-        will be called whenever a command adds an entry to the
-        run log, which can be used for display and progress
-        estimation. If specified, the callback should take a
-        single argument (the name doesn't matter) which will
-        be a dictionary:
-
-        .. code-block:: python
-
-          {
-            'name': command_name,
-            'payload': {
-              'text': string_command_text,
-              # The rest of this struct is
-              # command-dependent; see
-              # opentrons.legacy_commands.commands.
-             }
-          }
-
-        .. note::
-          In older software versions, ``payload["text"]`` was a
-          `format string <https://docs.python.org/3/library/string.html#formatstrings>`_.
-          To get human-readable text, you had to do ``payload["text"].format(**payload)``.
-          Don't do that anymore. If ``payload["text"]`` happens to contain any
-          ``{`` or ``}`` characters, it can confuse ``.format()`` and cause it to raise a
-          ``KeyError``.
-
-    :param custom_labware_paths: A list of directories to search for custom labware.
-        Loads valid labware from these paths and makes them available
-        to the protocol context. If this is ``None`` (the default), and
-        this function is called on a robot, it will look in the ``labware``
-        subdirectory of the Jupyter data directory.
-    :param custom_data_paths: A list of directories or files to load custom
-        data files from. Ignored if the apiv2 feature
-        flag if not set. Entries may be either files or
-        directories. Specified files and the
-        non-recursive contents of specified directories
-        are presented by the protocol context in
-        ``ProtocolContext.bundled_data``.
+    `opentrons_execute` or `python -m opentrons.execute`.
+
+    Args:
+        protocol_file: The protocol file to execute.
+        protocol_name: The name of the protocol file. This is required
+            internally, but it may not be a thing we can get
+            from the `protocol_file` argument.
+        propagate_logs: Whether this function should allow logs from the
+            Opentrons stack to propagate up to the root handler.
+            This can be useful if you're integrating this
+            function in a larger application, but most logs that
+            occur during protocol simulation are best associated
+            with the actions in the protocol that cause them.
+            Default: `False`.
+        log_level: The level of logs to emit on the command line:
+            `"debug"`, `"info"`, `"warning"`, or `"error"`.
+            Defaults to `"warning"`.
+        emit_runlog: A callback for printing the run log. If specified, this
+            will be called whenever a command adds an entry to the
+            run log, which can be used for display and progress
+            estimation. If specified, the callback should take a
+            single argument (the name doesn't matter) which will
+            be a dictionary:
+
+            ```python
+            {
+                'name': command_name,
+                'payload': {
+                    'text': string_command_text,
+                    # The rest of this struct is
+                    # command-dependent; see
+                    # opentrons.legacy_commands.commands.
+                }
+            }
+            ```
+
+            !!! note
+                In older software versions, `payload["text"]` was a
+                [format string](https://docs.python.org/3/library/string.html#formatstrings).
+                To get human-readable text, you had to do
+                `payload["text"].format(**payload)`. Don't do that anymore.
+                If `payload["text"]` happens to contain any `{` or `}`
+                characters, it can confuse `.format()` and cause it to raise
+                a `KeyError`.
+
+        custom_labware_paths: A list of directories to search for custom labware.
+            Loads valid labware from these paths and makes them available
+            to the protocol context. If this is `None` (the default), and
+            this function is called on a robot, it will look in the `labware`
+            subdirectory of the Jupyter data directory.
+        custom_data_paths: A list of directories or files to load custom
+            data files from. Ignored if the apiv2 feature
+            flag is not set. Entries may be either files or
+            directories. Specified files and the
+            non-recursive contents of specified directories
+            are presented by the protocol context in
+            `ProtocolContext.bundled_data`.
     """
     stack_logger = logging.getLogger("opentrons")
     stack_logger.propagate = propagate_logs
@@ -456,13 +465,17 @@ def _print_runlog(command: command_types.CommandMessage) -> None:
 
 
 def main() -> int:
-    """Handler for command line invocation to run a protocol.
+    """
+    Handler for command line invocation to run a protocol.
+
+    The arguments the program was invoked with are usually
+    [`sys.argv`](https://docs.python.org/3/library/sys.html#sys.argv)
+    but if you want to override that you can.
 
-    :param argv: The arguments the program was invoked with; this is usually
-        :py:obj:`sys.argv` but if you want to override that you can.
-    :returns int: A success or failure value suitable for use as a shell
-        return code passed to :py:obj:`sys.exit` (0 means success,
-        anything else is a kind of failure).
+    Returns:
+        int: A success or failure value suitable for use as a shell return code
+            passed to [`sys.exit`](https://docs.python.org/3/library/sys.html#sys.exit)
+            (0 means success, anything else is a kind of failure).
     """
     parser = argparse.ArgumentParser(
         prog="opentrons_execute", description="Run an OT-2 protocol"

api/src/opentrons/protocol_api/_liquid.py

@@ -29,7 +29,7 @@ class Liquid:
         description: An optional description.
         display_color: An optional display color for the liquid.
 
-    .. versionadded:: 2.14
+    *New in version 2.14*
     """
 
     _id: str

api/src/opentrons/protocol_api/_types.py

@@ -5,25 +5,21 @@
 
 # Implemented with an enum to support type narrowing via `== OFF_DECK`.
 class OffDeckType(enum.Enum):
-    """The type of the :py:obj:`OFF_DECK` constant.
+    """The type of the [`OFF_DECK`][opentrons.protocol_api.OFF_DECK] constant.
 
-    Do not use directly, except in type annotations and ``isinstance`` calls.
+    Do not use directly, except in type annotations and `isinstance` calls.
     """
 
     OFF_DECK = "off-deck"
     WASTE_CHUTE = "waste-chute"
 
 
 OFF_DECK: Final = OffDeckType.OFF_DECK
-WASTE_CHUTE: Final = OffDeckType.WASTE_CHUTE
-
-# Set __doc__ manually as a workaround. When this docstring is written the normal way, right after
-# the constant definition, Sphinx has trouble picking it up.
-OFF_DECK.__doc__ = """\
-A special location value, indicating that a labware is not currently on the robot's deck.
+"""A special location value, indicating that a labware is not currently on the robot's deck.
 
-See :ref:`off-deck-location` for details on using ``OFF_DECK`` with :py:obj:`ProtocolContext.move_labware()`.
+See [The Off-Deck Location][the-off-deck-location] for details on using `OFF_DECK` with [`ProtocolContext.move_labware()`][opentrons.protocol_api.ProtocolContext.move_labware].
 """
+WASTE_CHUTE: Final = OffDeckType.WASTE_CHUTE
 
 
 class PlungerPositionTypes(enum.Enum):

api/src/opentrons/protocol_api/disposal_locations.py

@@ -78,7 +78,7 @@ def height(self) -> float:
 class TrashBin(_DisposalLocation):
     """Represents a Flex or OT-2 trash bin.
 
-    See :py:meth:`.ProtocolContext.load_trash_bin`.
+    See [`load_trash_bin()`][opentrons.protocol_api.ProtocolContext.load_trash_bin].
     """
 
     def __init__(
@@ -103,11 +103,11 @@ def __init__(
     def top(self, x: float = 0, y: float = 0, z: float = 0) -> TrashBin:
         """Add a location offset to a trash bin.
 
-        The default location (``x``, ``y``, and ``z`` all set to ``0``) is the center of
+        The default location (`x`, `y`, and `z` all set to `0`) is the center of
         the bin on the x- and y-axes, and slightly below its physical top on the z-axis.
 
         Offsets can be positive or negative and are measured in mm.
-        See :ref:`protocol-api-deck-coords`.
+        See [Position Relative to the Deck][position-relative-to-the-deck].
         """
         return TrashBin(
             location=self._location,
@@ -163,7 +163,7 @@ def height(self) -> float:
 class WasteChute(_DisposalLocation):
     """Represents a Flex waste chute.
 
-    See :py:meth:`.ProtocolContext.load_waste_chute`.
+    See [`load_waste_chute()`][opentrons.protocol_api.ProtocolContext.load_waste_chute].
     """
 
     def __init__(
@@ -180,13 +180,13 @@ def __init__(
     def top(self, x: float = 0, y: float = 0, z: float = 0) -> WasteChute:
         """Add a location offset to a waste chute.
 
-        The default location (``x``, ``y``, and ``z`` all set to ``0``) is the center of
+        The default location (`x`, `y`, and `z` all set to `0`) is the center of
         the chute's opening on the x- and y-axes, and slightly below its physical top
-        on the z-axis. See :ref:`configure-waste-chute` for more information on possible
+        on the z-axis. See [Waste Chute][waste-chute-api] for more information on possible
         configurations of the chute.
 
         Offsets can be positive or negative and are measured in mm.
-        See :ref:`protocol-api-deck-coords`.
+        See [Position Relative to the Deck][position-relative-to-the-deck].
         """
         return WasteChute(
             engine_client=self._engine_client,