chore: resolve (or suppress) all Sphinx warnings (#14349)

api/Makefile

@@ -130,14 +130,11 @@ format:
 	$(python) -m black src tests setup.py
 
 docs/build/html/v%: docs/v%
-	$(sphinx_build_allow_warnings) -b html -d docs/build/doctrees -n $< $@
-# sphinx wont automatically do this because it's only in a template
-	$(SHX) cp docs/img/lightbulb.jpg $@/_images/
+	$(sphinx_build) -b html -d docs/build/doctrees -n $< $@
 
 docs/build/html/hardware: docs/hardware src/opentrons/hardware_control
 	$(sphinx_build_allow_warnings) -b html -d docs/build/doctrees -n $< $@
 	$(SHX) mkdir $@/_images/
-	$(SHX) cp docs/img/lightbulb.jpg $@/_images/
 
 docs/dist/v%: docs/build/html/v%
 	$(SHX) mkdir -p $@

api/docs/v2/complex_commands/sources_destinations.rst

@@ -103,7 +103,7 @@ Aspirating and Dispensing
 See :ref:`complex-tip-refilling` below for cases where the total amount to be dispensed is greater than the capacity of the tip.
 
 .. figure:: ../../img/complex_commands/robot_distribute.png
-    :name: Transfer
+    :name: Distribute
     :scale: 35%
     :align: center
 
@@ -120,7 +120,7 @@ See :ref:`complex-tip-refilling` below for cases where the total amount to be di
 See :ref:`complex-tip-refilling` below for cases where the total amount to be aspirated is greater than the capacity of the tip.
 
 .. figure:: ../../img/complex_commands/robot_consolidate.png
-    :name: Transfer
+    :name: Consolidate
     :scale: 35%
     :align: center
 

api/docs/v2/conf.py

@@ -424,3 +424,26 @@
 # -- Options for tabs -----------------------------------------------------
 
 sphinx_tabs_disable_tab_closing = True
+
+# -- Suppress autodoc warnings --------------------------------------------
+
+# Ignore warnings for deliberately missing/undocumented things that appear
+# in automatically generated type signatures.
+#
+# The goal here is to pass through any warnings for bad targets of MANUALLY
+# created links.
+nitpick_ignore_regex = [
+    ("py:class", r".*Optional\[.*"),  # any Optional with bad members
+    ("py:class", r".*commands\.types.*"),
+    ("py:class", r".*hardware_control.*"),
+    ("py:class", r".*legacy_broker.*"),
+    ("py:class", r".*protocol_api\.core.*"),
+    ("py:class", r".*api_support.*"),
+    ("py:class", r".*duration\.estimator.*"),
+    ("py:class", r".*protocols\.types.*"),
+    ("py:class", r".*protocol_api\.deck.*"),
+    ("py:class", r".*protocol_api\.config.*"),
+    ("py:class", r".*opentrons_shared_data.*"),
+    ("py:class", r".*types\.DeckSlotName.*"),  # TODO: RTC-386
+    ("py:class", r'.*AbstractLabware|APIVersion|LabwareLike|LoadedCoreMap|ModuleTypes|NoneType|OffDeckType|ProtocolCore|WellCore'),  # laundry list of not fully qualified things
+]

api/docs/v2/deck_slots.rst

@@ -110,7 +110,7 @@ Which fixtures you need to configure depend on both load methods and the effects
 Staging Area Slots
 ------------------
 
-Slots A4 through D4 are the staging area slots. Pipettes can't reach the staging area, but these slots are always available in the API for loading and moving labware. Using a slot in column 4 as the ``location`` argument of :py:meth:`.load_labware` or the ``new_location`` argument of :py:meth:`.move_labware` will require the corresponding staging area slot in the robot's deck configuration::
+Slots A4 through D4 are the staging area slots. Pipettes can't reach the staging area, but these slots are always available in the API for loading and moving labware. Using a slot in column 4 as the ``location`` argument of :py:meth:`~.ProtocolContext.load_labware` or the ``new_location`` argument of :py:meth:`.move_labware` will require the corresponding staging area slot in the robot's deck configuration::
 
     plate_1 = protocol.load_labware(
         load_name="corning_96_wellplate_360ul_flat", location="C3"
@@ -150,7 +150,7 @@ Starting in API version 2.16, you must load trash bin fixtures in your protocol
 .. versionadded:: 2.16
 
 .. note::
-    The :py:class:`TrashBin` class doesn't have any callable methods, so you don't have to save the result of ``load_trash_bin()`` to a variable, especially if your protocol only loads a single trash container. Being able to reference the trash bin by name is useful when dealing with multiple trash containers.
+    The :py:class:`.TrashBin` class doesn't have any callable methods, so you don't have to save the result of ``load_trash_bin()`` to a variable, especially if your protocol only loads a single trash container. Being able to reference the trash bin by name is useful when dealing with multiple trash containers.
 
 Call ``load_trash_bin()`` multiple times to add more than one bin. See :ref:`pipette-trash-containers` for more information on using pipettes with multiple trash bins.
 
@@ -169,7 +169,7 @@ To use the waste chute, first use :py:meth:`.load_waste_chute` to load it in slo
 
 The ``load_waste_chute()`` method takes no arguments, since D3 is the only valid location for the chute. However, there are multiple variant configurations of the waste chute, depending on how other methods in your protocol use it.
 
-The waste chute is installed either on a standard deck plate adapter or on a deck plate adapter with a staging area. If any :py:meth:`.load_labware` or :py:meth:`.move_labware` calls in your protocol reference slot D4, you have to use the deck plate adapter with staging area.
+The waste chute is installed either on a standard deck plate adapter or on a deck plate adapter with a staging area. If any :py:meth:`~.ProtocolContext.load_labware` or :py:meth:`.move_labware` calls in your protocol reference slot D4, you have to use the deck plate adapter with staging area.
 
 The waste chute has a removable cover with a narrow opening which helps prevent aerosols and droplets from contaminating the working area. 1- and 8-channel pipettes can dispense liquid, blow out, or drop tips through the opening in the cover. Any of the following require you to remove the cover. 
 

api/docs/v2/index.rst

@@ -36,7 +36,7 @@ Getting Started
 
 If you want to **dive right into code**, take a look at our :ref:`new-examples` and the comprehensive :ref:`protocol-api-reference`.
 
-When you're ready to **try out a protocol**, download the `Opentrons App <https://www.opentrons.com/ot-app>`_, import the protocol file, and run it on your robot.
+When you're ready to **try out a protocol**, download the `Opentrons App <https://www.opentrons.com/ot-app>`__, import the protocol file, and run it on your robot.
 
 
 .. _overview-section-v2:
@@ -170,7 +170,7 @@ More Resources
 Opentrons App
 +++++++++++++
 
-The `Opentrons App <https://opentrons.com/ot-app/>`_ is the easiest way to run your Python protocols. The app `supports <https://support.opentrons.com/en/articles/2687536-get-started-supported-operating-systems-for-the-opentrons-app>`_ the latest versions of macOS, Windows, and Ubuntu.
+The `Opentrons App <https://opentrons.com/ot-app/>`__ is the easiest way to run your Python protocols. The app `supports <https://support.opentrons.com/en/articles/2687536-get-started-supported-operating-systems-for-the-opentrons-app>`_ the latest versions of macOS, Windows, and Ubuntu.
 
 Support
 +++++++

api/docs/v2/moving_labware.rst

@@ -132,7 +132,7 @@ If the labware is inaccessible, the API will raise an error.
 Movement into the Waste Chute
 =============================
 
-Move used tip racks and well plates to the waste chute to dispose of them. This requires you to first :ref:`configure the waste chute <configure-waste-chute>` in your protocol. Then use the loaded :py:class:`WasteChute` object as the value of ``new_location``::
+Move used tip racks and well plates to the waste chute to dispose of them. This requires you to first :ref:`configure the waste chute <configure-waste-chute>` in your protocol. Then use the loaded :py:class:`.WasteChute` object as the value of ``new_location``::
 
     chute = protocol.load_waste_chute()
     protocol.move_labware(

api/docs/v2/new_advanced_running.rst

@@ -145,6 +145,7 @@ Command Line
 ------------
 
 .. TODO update with separate links to OT-2 and Flex setup, when new Flex process is in manual or on help site
+
 The robot's command line is accessible either by going to **New > Terminal** in Jupyter or `via SSH <https://support.opentrons.com/s/article/Connecting-to-your-OT-2-with-SSH>`_.
 
 To execute a protocol from the robot's command line, copy the protocol file to the robot with ``scp`` and then run the protocol with ``opentrons_execute``:

api/docs/v2/new_protocol_api.rst

@@ -30,6 +30,11 @@ Labware
    :members:
    :exclude-members: next_tip, use_tips, previous_tip, return_tips
 
+.. autoclass:: opentrons.protocol_api.TrashBin
+
+.. autoclass:: opentrons.protocol_api.WasteChute
+
+
 Wells and Liquids
 =================
 .. autoclass:: opentrons.protocol_api.Well

api/docs/v2/pipettes/partial_tip_pickup.rst

@@ -180,7 +180,7 @@ First, tip tracking is not available with column 1. You must always specify a ``
     pipette.pick_up_tip(row_a.pop())  # pick up A11-H11
     pipette.drop_tip()
 
-This code first constructs a list of all the wells in row A of the tip rack. Then, when picking up a tip, instead of referencing one of those wells directly, the ``location`` is set to ``row_a.pop()``. This uses the built-in :py:meth:`pop` method to get the last item from the list and remove it from the list. If you keep using this approach to pick up tips, you'll get an error once the tip rack is empty — not from the API, but from Python itself, since you're trying to ``pop`` an item from an empty list.
+This code first constructs a list of all the wells in row A of the tip rack. Then, when picking up a tip, instead of referencing one of those wells directly, the ``location`` is set to ``row_a.pop()``. This uses the `built-in pop method <https://docs.python.org/3/tutorial/datastructures.html#more-on-lists>`_ to get the last item from the list and remove it from the list. If you keep using this approach to pick up tips, you'll get an error once the tip rack is empty — not from the API, but from Python itself, since you're trying to ``pop`` an item from an empty list.
 
 Second, the API does not provide the same collision detection for the column 1 layout that it does for column 12.
 

api/docs/v2/versioning.rst

@@ -182,13 +182,13 @@ This version introduces support for the Opentrons Flex robot, instruments, modul
 
   - Use coordinates or numbers to specify :ref:`deck slots <deck-slots>`. These formats match physical labels on Flex and OT-2, but you can use either system, regardless of ``robotType``.
 
-  - The new :py:meth:`.load_adapter` method lets you load adapters and labware separately on modules, and lets you load adapters directly in deck slots. See :ref:`labware-on-adapters`.
+  - The new module context ``load_adapter()`` methods let you load adapters and labware separately on modules, and :py:meth:`.ProtocolContext.load_adapter` lets you load adapters directly in deck slots. See :ref:`labware-on-adapters`.
 
   - Move labware manually using :py:meth:`.move_labware`, without having to stop your protocol. 
 
   - Manual labware moves support moving to or from the new :py:obj:`~.protocol_api.OFF_DECK` location (outside of the robot).
 
-  - :py:meth:`.load_labware` also accepts :py:obj:`~.protocol_api.OFF_DECK` as a location. This lets you prepare labware to be moved onto the deck later in a protocol.  
+  - :py:meth:`.ProtocolContext.load_labware` also accepts :py:obj:`~.protocol_api.OFF_DECK` as a location. This lets you prepare labware to be moved onto the deck later in a protocol.
 
   - The new ``push_out`` parameter of the :py:meth:`.dispense` method helps ensure that the pipette dispenses all of its liquid when working with very small volumes.
 
@@ -244,10 +244,10 @@ If you specify an API version of ``2.13`` or lower, your protocols will continue
     because the plunger's speed is a stepwise function of the volume.
     Use :py:attr:`.InstrumentContext.flow_rate` to set the flow rate in µL/s, instead.
 
-  - ``ModuleContext.load_labware_object`` was removed as an unnecessary internal method.
+  - ``load_labware_object()`` was removed from module contexts as an unnecessary internal method.
 
-  - ``ModuleContext.geometry`` was removed in favor of
-    :py:attr:`.ModuleContext.model` and :py:attr:`.ModuleContext.type`
+  - ``geometry`` was removed from module contexts in favor of
+    ``model`` and ``type`` attributes.
 
   - ``Well.geometry`` was removed as unnecessary.
 
@@ -337,7 +337,7 @@ Version 2.8
 Version 2.7
 -----------
 
-- Added :py:meth:`.InstrumentContext.pair_with`, an experimental feature for moving both pipettes simultaneously.
+- Added ``InstrumentContext.pair_with()``, an experimental feature for moving both pipettes simultaneously.
 
   .. note::
 

api/src/opentrons/protocol_api/_trash_bin.py

@@ -4,7 +4,7 @@
 class TrashBin:
     """Represents a Flex trash bin.
 
-    See :py:obj:`ProtocolContext.load_trash_bin`.
+    See :py:meth:`.ProtocolContext.load_trash_bin`.
     """
 
     def __init__(self, location: DeckSlotName, addressable_area_name: str) -> None:

api/src/opentrons/protocol_api/_waste_chute.py

@@ -1,5 +1,5 @@
 class WasteChute:
     """Represents a Flex waste chute.
 
-    See :py:obj:`ProtocolContext.load_waste_chute`.
+    See :py:meth:`.ProtocolContext.load_waste_chute`.
     """

api/src/opentrons/protocol_api/instrument_context.py

@@ -980,10 +980,10 @@ def drop_tip(
               unusually large height above the tip rack, you could call
               ``pipette.drop_tip(tip_rack["A1"].top(z=10))``.
             - As a :py:class:`.TrashBin`. This uses a default location relative to the
-              TrashBin object. For example,
+              ``TrashBin`` object. For example,
               ``pipette.drop_tip(location=trash_bin)``.
             - As a :py:class:`.WasteChute`. This uses a default location relative to
-              the WasteChute object. For example,
+              the ``WasteChute`` object. For example,
               ``pipette.drop_tip(location=waste_chute)``.
 
         :param location:
@@ -1543,7 +1543,7 @@ def trash_container(self) -> Union[labware.Labware, TrashBin, WasteChute]:
         This is the property used to determine where to drop tips and blow out liquids
         when calling :py:meth:`drop_tip` or :py:meth:`blow_out` without arguments.
 
-        You can set this to a :py:obj:`Labware`, :py:obj:`TrashBin`, or :py:obj:`WasteChute`.
+        You can set this to a :py:obj:`Labware`, :py:class:`.TrashBin`, or :py:class:`.WasteChute`.
 
         The default value depends on the robot type and API version:
 

api/src/opentrons/protocol_api/labware.py

@@ -393,17 +393,17 @@ def parent(self) -> Union[str, Labware, ModuleTypes, OffDeckType]:
             If the labware is directly on the robot's deck, the ``str`` name of the deck slot,
             like ``"D1"`` (Flex) or ``"1"`` (OT-2). See :ref:`deck-slots`.
 
-            If the labware is on a module, a :py:class:`ModuleContext`.
+            If the labware is on a module, a module context.
 
             If the labware is on a labware or adapter, a :py:class:`Labware`.
 
             If the labware is off-deck, :py:obj:`OFF_DECK`.
 
         .. versionchanged:: 2.14
-            Return type for module parent changed to :py:class:`ModuleContext`.
-            Prior to this version, an internal geometry interface is returned.
+            Return type for module parent changed.
+            Prior to this version, an internal geometry interface was returned.
         .. versionchanged:: 2.15
-            Will return a :py:class:`Labware` if the labware was loaded onto a labware/adapter.
+            Will return a :py:class:`Labware` if the labware is loaded onto a labware/adapter.
             Will now return :py:obj:`OFF_DECK` if the labware is off-deck.
             Formerly, if the labware was removed by using ``del`` on :py:obj:`.deck`,
             this would return where it was before its removal.

api/src/opentrons/protocol_api/protocol_context.py

@@ -1029,7 +1029,7 @@ def deck(self) -> Deck:
         will all return the object loaded in the front-left slot. (See :ref:`deck-slots`.)
 
         The value will be a :py:obj:`~opentrons.protocol_api.Labware` if the slot contains a
-        labware, a :py:obj:`~opentrons.protocol_api.ModuleContext` if the slot contains a hardware
+        labware, a module context if the slot contains a hardware
         module, or ``None`` if the slot doesn't contain anything.
 
         Rather than filtering the objects in the deck map yourself,
@@ -1064,7 +1064,7 @@ def fixed_trash(self) -> Union[Labware, TrashBin]:
         In API version 2.16 and later, the fixed trash only exists in OT-2 protocols. It is a :py:class:`.TrashBin` object, which doesn't have any wells. Trying to access ``fixed_trash`` in a Flex protocol will raise an error. See :ref:`configure-trash-bin` for details on using the movable trash in Flex protocols.
 
         .. versionchanged:: 2.16
-            Returns a :py:class:`.TrashBin` object.
+            Returns a ``TrashBin`` object.
         """
         if self._api_version >= APIVersion(2, 16):
             if self._core.robot_type == "OT-3 Standard":