From 26f8ea431ca75881c71a24d887b85daae1d4738c Mon Sep 17 00:00:00 2001
From: Max Marrone <max@opentrons.com>
Date: Fri, 1 Oct 2021 15:07:25 -0400
Subject: [PATCH] docs(api): Fix various documentation formatting problems
 (#8444)

Closes #8260.
---
 api/docs/Makefile                             | 225 --------------
 api/docs/make.bat                             | 281 ------------------
 api/docs/v2/index.rst                         |   8 +-
 api/docs/v2/new_advanced_running.rst          |  12 +-
 api/docs/v2/new_complex_commands.rst          |   8 +-
 api/docs/v2/new_modules.rst                   |  15 +-
 api/docs/v2/new_pipette.rst                   |  69 ++---
 api/docs/v2/versioning.rst                    |  41 ++-
 api/src/opentrons/hardware_control/api.py     |   2 +-
 .../protocol_api/instrument_context.py        |  47 ++-
 api/src/opentrons/protocol_api/labware.py     |  10 +-
 .../protocol_api/protocol_context.py          |   9 +-
 api/src/opentrons/simulate.py                 |  15 +-
 13 files changed, 129 insertions(+), 613 deletions(-)
 delete mode 100644 api/docs/Makefile
 delete mode 100644 api/docs/make.bat

diff --git a/api/docs/Makefile b/api/docs/Makefile
deleted file mode 100644
index f6c65d93600..00000000000
--- a/api/docs/Makefile
+++ /dev/null
@@ -1,225 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = build
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-
-.PHONY: help
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  applehelp  to make an Apple Help Book"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  epub3      to make an epub3"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-	@echo "  coverage   to run coverage check of the documentation (if enabled)"
-	@echo "  dummy      to check syntax errors of document sources"
-
-.PHONY: clean
-clean:
-	rm -rf $(BUILDDIR)/*
-
-.PHONY: html
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-.PHONY: dirhtml
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-.PHONY: singlehtml
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-.PHONY: pickle
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-.PHONY: json
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-.PHONY: htmlhelp
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-.PHONY: qthelp
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/OpentronsAPI.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/OpentronsAPI.qhc"
-
-.PHONY: applehelp
-applehelp:
-	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
-	@echo
-	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
-	@echo "N.B. You won't be able to view it unless you put it in" \
-	      "~/Library/Documentation/Help or install it in your application" \
-	      "bundle."
-
-.PHONY: devhelp
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/OpentronsAPI"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/OpentronsAPI"
-	@echo "# devhelp"
-
-.PHONY: epub
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-.PHONY: epub3
-epub3:
-	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
-	@echo
-	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
-
-.PHONY: latex
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-.PHONY: latexpdf
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-.PHONY: latexpdfja
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-.PHONY: text
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-.PHONY: man
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-.PHONY: texinfo
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-.PHONY: info
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-.PHONY: gettext
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-.PHONY: changes
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-.PHONY: linkcheck
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-.PHONY: doctest
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
-
-.PHONY: coverage
-coverage:
-	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
-	@echo "Testing of coverage in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/coverage/python.txt."
-
-.PHONY: xml
-xml:
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
-
-.PHONY: pseudoxml
-pseudoxml:
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
-
-.PHONY: dummy
-dummy:
-	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
-	@echo
-	@echo "Build finished. Dummy builder generates no files."
diff --git a/api/docs/make.bat b/api/docs/make.bat
deleted file mode 100644
index a7fc9dce438..00000000000
--- a/api/docs/make.bat
+++ /dev/null
@@ -1,281 +0,0 @@
-@ECHO OFF
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set BUILDDIR=build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
-set I18NSPHINXOPTS=%SPHINXOPTS% source
-if NOT "%PAPER%" == "" (
-	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
-	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
-)
-
-if "%1" == "" goto help
-
-if "%1" == "help" (
-	:help
-	echo.Please use `make ^<target^>` where ^<target^> is one of
-	echo.  html       to make standalone HTML files
-	echo.  dirhtml    to make HTML files named index.html in directories
-	echo.  singlehtml to make a single large HTML file
-	echo.  pickle     to make pickle files
-	echo.  json       to make JSON files
-	echo.  htmlhelp   to make HTML files and a HTML help project
-	echo.  qthelp     to make HTML files and a qthelp project
-	echo.  devhelp    to make HTML files and a Devhelp project
-	echo.  epub       to make an epub
-	echo.  epub3      to make an epub3
-	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
-	echo.  text       to make text files
-	echo.  man        to make manual pages
-	echo.  texinfo    to make Texinfo files
-	echo.  gettext    to make PO message catalogs
-	echo.  changes    to make an overview over all changed/added/deprecated items
-	echo.  xml        to make Docutils-native XML files
-	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
-	echo.  linkcheck  to check all external links for integrity
-	echo.  doctest    to run all doctests embedded in the documentation if enabled
-	echo.  coverage   to run coverage check of the documentation if enabled
-	echo.  dummy      to check syntax errors of document sources
-	goto end
-)
-
-if "%1" == "clean" (
-	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
-	del /q /s %BUILDDIR%\*
-	goto end
-)
-
-
-REM Check if sphinx-build is available and fallback to Python version if any
-%SPHINXBUILD% 1>NUL 2>NUL
-if errorlevel 9009 goto sphinx_python
-goto sphinx_ok
-
-:sphinx_python
-
-set SPHINXBUILD=python -m sphinx.__init__
-%SPHINXBUILD% 2> nul
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-:sphinx_ok
-
-
-if "%1" == "html" (
-	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
-	goto end
-)
-
-if "%1" == "dirhtml" (
-	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
-	goto end
-)
-
-if "%1" == "singlehtml" (
-	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
-	goto end
-)
-
-if "%1" == "pickle" (
-	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can process the pickle files.
-	goto end
-)
-
-if "%1" == "json" (
-	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can process the JSON files.
-	goto end
-)
-
-if "%1" == "htmlhelp" (
-	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can run HTML Help Workshop with the ^
-.hhp project file in %BUILDDIR%/htmlhelp.
-	goto end
-)
-
-if "%1" == "qthelp" (
-	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can run "qcollectiongenerator" with the ^
-.qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\OpentronsAPI.qhcp
-	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\OpentronsAPI.ghc
-	goto end
-)
-
-if "%1" == "devhelp" (
-	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished.
-	goto end
-)
-
-if "%1" == "epub" (
-	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The epub file is in %BUILDDIR%/epub.
-	goto end
-)
-
-if "%1" == "epub3" (
-	%SPHINXBUILD% -b epub3 %ALLSPHINXOPTS% %BUILDDIR%/epub3
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The epub3 file is in %BUILDDIR%/epub3.
-	goto end
-)
-
-if "%1" == "latex" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "latexpdf" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	cd %BUILDDIR%/latex
-	make all-pdf
-	cd %~dp0
-	echo.
-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "latexpdfja" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	cd %BUILDDIR%/latex
-	make all-pdf-ja
-	cd %~dp0
-	echo.
-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "text" (
-	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The text files are in %BUILDDIR%/text.
-	goto end
-)
-
-if "%1" == "man" (
-	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The manual pages are in %BUILDDIR%/man.
-	goto end
-)
-
-if "%1" == "texinfo" (
-	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
-	goto end
-)
-
-if "%1" == "gettext" (
-	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
-	goto end
-)
-
-if "%1" == "changes" (
-	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.The overview file is in %BUILDDIR%/changes.
-	goto end
-)
-
-if "%1" == "linkcheck" (
-	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Link check complete; look for any errors in the above output ^
-or in %BUILDDIR%/linkcheck/output.txt.
-	goto end
-)
-
-if "%1" == "doctest" (
-	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Testing of doctests in the sources finished, look at the ^
-results in %BUILDDIR%/doctest/output.txt.
-	goto end
-)
-
-if "%1" == "coverage" (
-	%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Testing of coverage in the sources finished, look at the ^
-results in %BUILDDIR%/coverage/python.txt.
-	goto end
-)
-
-if "%1" == "xml" (
-	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The XML files are in %BUILDDIR%/xml.
-	goto end
-)
-
-if "%1" == "pseudoxml" (
-	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
-	goto end
-)
-
-if "%1" == "dummy" (
-	%SPHINXBUILD% -b dummy %ALLSPHINXOPTS% %BUILDDIR%/dummy
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. Dummy builder generates no files.
-	goto end
-)
-
-:end
diff --git a/api/docs/v2/index.rst b/api/docs/v2/index.rst
index abbe5eea730..c11c1f4fbdc 100644
--- a/api/docs/v2/index.rst
+++ b/api/docs/v2/index.rst
@@ -114,12 +114,12 @@ Protocols are structured around a function called ``run(protocol)``, defined in
 .. code-block:: python
     :substitutions:
 
-   from opentrons import protocol_api
+    from opentrons import protocol_api
 
-   metadata = {'apiLevel': '|apiLevel|'}
+    metadata = {'apiLevel': '|apiLevel|'}
 
-   def run(protocol: protocol_api.ProtocolContext):
-       pass
+    def run(protocol: protocol_api.ProtocolContext):
+        pass
 
 This function must be named exactly ``run`` and must take exactly one mandatory argument (its name doesn’t matter, but we recommend ``protocol`` since this argument represents the protocol that the robot will execute).
 
diff --git a/api/docs/v2/new_advanced_running.rst b/api/docs/v2/new_advanced_running.rst
index 5dfd0bbbb8b..ee7414049fb 100644
--- a/api/docs/v2/new_advanced_running.rst
+++ b/api/docs/v2/new_advanced_running.rst
@@ -54,13 +54,13 @@ If you have a protocol that you have already written you can run it directly in
 .. code-block:: python
     :substitutions:
 
-   import opentrons.execute
-   from opentrons import protocol_api
-   def run(protocol: protocol_api.ProtocolContext):
-       # the contents of your protocol are here...
+    import opentrons.execute
+    from opentrons import protocol_api
+    def run(protocol: protocol_api.ProtocolContext):
+        # the contents of your protocol are here...
 
-   protocol = opentrons.execute.get_protocol_api('|apiLevel|')
-   run(protocol)  # your protocol will now run
+    protocol = opentrons.execute.get_protocol_api('|apiLevel|')
+    run(protocol)  # your protocol will now run
 
 
 Custom Labware
diff --git a/api/docs/v2/new_complex_commands.rst b/api/docs/v2/new_complex_commands.rst
index fe2047044bf..1dc4d8a9400 100644
--- a/api/docs/v2/new_complex_commands.rst
+++ b/api/docs/v2/new_complex_commands.rst
@@ -580,7 +580,7 @@ If you want to avoid cross-contamination and increase accuracy, you should set t
 .. versionadded:: 2.0
 
 Always Get a New Tip
-^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++
 
 Transfer commands will by default use the same tip for each well, then finally drop it in the trash once finished.
 
@@ -615,7 +615,7 @@ will have the steps...
 
 
 Never Get a New Tip
-^^^^^^^^^^^^^^^^^^^
++++++++++++++++++++
 
 For scenarios where you instead are calling ``pick_up_tip()`` and ``drop_tip()`` elsewhere in your protocol, the transfer command can ignore picking up or dropping tips.
 
@@ -650,7 +650,7 @@ will have the steps...
 
 
 Use One Tip
-^^^^^^^^^^^
++++++++++++
 
 The default behavior of complex commands is to use one tip:
 
@@ -828,7 +828,7 @@ For example, to blow out in the destination well you can do the following:
 
 .. note::
 
-You *must* specify ``blow_out=True`` in order to utilize the new argument ``blowout_location``
+    You *must* specify ``blow_out=True`` in order to utilize the new argument ``blowout_location``
 
 
 
diff --git a/api/docs/v2/new_modules.rst b/api/docs/v2/new_modules.rst
index 232de0dc622..78caffa9c72 100644
--- a/api/docs/v2/new_modules.rst
+++ b/api/docs/v2/new_modules.rst
@@ -103,7 +103,8 @@ Recommended Magnetic Module GEN2 bead attraction time:
 Loading Labware Onto Your Module
 ================================
 
-Like specifying labware that will be present on the deck of the OT-2, you must specify labware that will be present on the module you have just loaded. You do this using :py:meth:`.ModuleContext.load_labware`. For instance, to load a Temperature Module and specify an `aluminum block for 2 mL tubes <https://labware.opentrons.com/opentrons_24_aluminumblock_generic_2ml_screwcap?category=aluminumBlock>`_, you would do:
+Like specifying labware that will be present on the deck of the OT-2, you must specify labware that will be present on the module you have just loaded.
+You do this using ``module.load_labware()``. For instance, to load a Temperature Module and specify an `aluminum block for 2 mL tubes <https://labware.opentrons.com/opentrons_24_aluminumblock_generic_2ml_screwcap?category=aluminumBlock>`_, you would do:
 
 .. code-block:: python
     :substitutions:
@@ -117,6 +118,11 @@ Like specifying labware that will be present on the deck of the OT-2, you must s
          my_labware = module.load_labware('opentrons_24_aluminumblock_generic_2ml_screwcap',
                                           label='Temperature-Controlled Tubes')
 
+See
+:py:meth:`.MagneticModuleContext.load_labware`,
+:py:meth:`.TemperatureModuleContext.load_labware`,
+or :py:meth:`.ThermocyclerContext.load_labware`.
+
 Notice that when you load labware on a module, you don't specify the labware's deck slot.  The labware is loaded on the module, on whichever deck slot the module occupies.
 
 
@@ -139,7 +145,7 @@ Any custom labware added to your Opentrons App (see :ref:`v2-custom-labware`) is
 
 .. note::
 
-    In API version 2.0, :py:meth:`.ModuleContext.load_labware` only took a ``load_name`` argument. In API version 2.1 (introduced in Robot Software version 3.15.2) or higher you can now specify a label, version, and namespace (though most of the time you won't have to).
+    In API version 2.0, ``module.load_labware()`` only took a ``load_name`` argument. In API version 2.1 (introduced in Robot Software version 3.15.2) or higher you can now specify a label, version, and namespace (though most of the time you won't have to).
 
 
 **************************
@@ -516,7 +522,10 @@ a few methods that allow you to do that.
 Basic Status
 ------------
 
-The :py:obj:`.ThermocyclerContext.status` property is one of the strings ``‘holding at target’``, ``‘cooling’``, ``‘heating’``, or ``‘idle’``.
+..
+    TODO(mm, 2021-09-30): We should be able to cross-reference to ThermocyclerContext.status, but it appears to not actually exist?
+
+The ``ThermocyclerContext.status`` property is one of the strings ``‘holding at target’``, ``‘cooling’``, ``‘heating’``, or ``‘idle’``.
 
 .. code-block:: python
 
diff --git a/api/docs/v2/new_pipette.rst b/api/docs/v2/new_pipette.rst
index 730fd830f49..b33e20340ae 100644
--- a/api/docs/v2/new_pipette.rst
+++ b/api/docs/v2/new_pipette.rst
@@ -39,6 +39,7 @@ Pipettes are specified in a protocol using the method :py:meth:`.ProtocolContext
     When you load a pipette in a protocol, you inform the OT-2 that you want the specified pipette to be present. Even if you do not use the pipette anywhere else in your protocol, the Opentrons App and the OT-2 will not let your protocol proceed until all pipettes loaded with ``load_instrument`` are attached to the OT-2.
 
 .. _new-multichannel-pipettes:
+
 Multi-Channel Pipettes
 ======================
 
@@ -201,40 +202,40 @@ For instance, in this protocol you can see the effects of specifying tipracks:
 .. code-block:: python
     :substitutions:
 
-   from opentrons import protocol_api
-
-   metadata = {'apiLevel': '|apiLevel|'}
-
-   def run(protocol: protocol_api.ProtocolContext):
-       tiprack_left = protocol.load_labware('opentrons_96_tiprack_300ul', '1')
-       tiprack_right = protocol.load_labware('opentrons_96_tiprack_300ul', '2')
-       left_pipette = protocol.load_instrument('p300_single', 'left')
-       right_pipette = protocol.load_instrument(
-           'p300_multi', 'right', tip_racks=[tiprack_right])
-
-       # You must specify the tip location for the left pipette, which was
-       # loaded without specifying tip_racks
-       left_pipette.pick_up_tip(tiprack['A1'])
-       left_pipette.drop_tip()
-
-       # And you have to do it every time you call pick_up_tip, doing all
-       # your own tip tracking
-       left_pipette.pick_up_tip(tiprack['A2'])
-       left_pipette.drop_tip()
-       left_pipette.pick_up_tip(tiprack['A3'])
-       left_pipette.drop_tip()
-
-       # Since you specified tip_racks when loading the right pipette, it will
-       # automatically pick up from A1 of its associated tiprack
-       right_pipette.pick_up_tip()
-       right_pipette.drop_tip()
-
-       # And further calls to pick_up_tip will automatically progress through
-       # the tips in the rack
-       right_pipette.pick_up_tip()
-       right_pipette.drop_tip()
-       right_pipette.pick_up_tip()
-       right_pipette.drop_tip()
+    from opentrons import protocol_api
+
+    metadata = {'apiLevel': '|apiLevel|'}
+
+    def run(protocol: protocol_api.ProtocolContext):
+        tiprack_left = protocol.load_labware('opentrons_96_tiprack_300ul', '1')
+        tiprack_right = protocol.load_labware('opentrons_96_tiprack_300ul', '2')
+        left_pipette = protocol.load_instrument('p300_single', 'left')
+        right_pipette = protocol.load_instrument(
+            'p300_multi', 'right', tip_racks=[tiprack_right])
+
+        # You must specify the tip location for the left pipette, which was
+        # loaded without specifying tip_racks
+        left_pipette.pick_up_tip(tiprack['A1'])
+        left_pipette.drop_tip()
+
+        # And you have to do it every time you call pick_up_tip, doing all
+        # your own tip tracking
+        left_pipette.pick_up_tip(tiprack['A2'])
+        left_pipette.drop_tip()
+        left_pipette.pick_up_tip(tiprack['A3'])
+        left_pipette.drop_tip()
+
+        # Since you specified tip_racks when loading the right pipette, it will
+        # automatically pick up from A1 of its associated tiprack
+        right_pipette.pick_up_tip()
+        right_pipette.drop_tip()
+
+        # And further calls to pick_up_tip will automatically progress through
+        # the tips in the rack
+        right_pipette.pick_up_tip()
+        right_pipette.drop_tip()
+        right_pipette.pick_up_tip()
+        right_pipette.drop_tip()
        
 
 This is further discussed in :ref:`v2-atomic-commands`
diff --git a/api/docs/v2/versioning.rst b/api/docs/v2/versioning.rst
index c2b3eacdaf3..3a5c90123e9 100644
--- a/api/docs/v2/versioning.rst
+++ b/api/docs/v2/versioning.rst
@@ -124,9 +124,11 @@ Changes in API Versions
 Version 2.1
 +++++++++++
 
-- You can now specify a label when loading labware into a module with the ``label`` parameter of
-  :py:meth:`.ModuleContext.load_labware` just like you can when loading labware
-  into your protocol with :py:meth:`.ProtocolContext.load_labware`.
+- When loading labware onto a module, you can now specify a label with the ``label`` parameter of
+  :py:meth:`.MagneticModuleContext.load_labware`,
+  :py:meth:`.TemperatureModuleContext.load_labware`,
+  :py:meth:`.ThermocyclerContext.load_labware`,
+  just like you can when loading labware onto the deck with :py:meth:`.ProtocolContext.load_labware`.
 
 
 Version 2.2
@@ -148,25 +150,27 @@ Version 2.3
   possible collisions
 - During a :ref:`mix`, the pipette will no longer move up to clear the liquid in
   between every dispense and following aspirate
-- You can now access the temperature module's status via the ``status`` property of ```ModuleContext.TemperatureModuleContext```
+- You can now access the temperature module's status via :py:obj:`.TemperatureModuleContext.status`.
 
 
 Version 2.4
 +++++++++++
 
 - The following improvements were made to the `touch_tip` command:
-    - The speed for `touch_tip` can now be lowered down to 1 mm/s
-    - `touch_tip` no longer moves diagonally from the X direction -> Y direction
-    - Takes into account geometry of the deck and modules
+
+  - The speed for ``touch_tip`` can now be lowered down to 1 mm/s
+  - ``touch_tip`` no longer moves diagonally from the X direction -> Y direction
+  - Takes into account geometry of the deck and modules
 
 
 Version 2.5
 +++++++++++
 
 - New :ref:`new-utility-commands` were added:
-    - :py:meth:`.ProtocolContext.set_rail_lights`: turns robot rail lights on or off
-    - :py:obj:`.ProtocolContext.rail_lights_on`: describes whether or not the rail lights are on
-    - :py:obj:`.ProtocolContext.door_closed`: describes whether the robot door is closed
+
+  - :py:meth:`.ProtocolContext.set_rail_lights`: turns robot rail lights on or off
+  - :py:obj:`.ProtocolContext.rail_lights_on`: describes whether or not the rail lights are on
+  - :py:obj:`.ProtocolContext.door_closed`: describes whether the robot door is closed
 
 
 Version 2.6
@@ -174,8 +178,10 @@ Version 2.6
 
 - GEN2 Single pipettes now default to flow rates equivalent to 10 mm/s plunger
   speeds
-    - Protocols that manually configure pipette flow rates will be unaffected
-    - For a comparison between API Versions, see :ref:`defaults`
+
+  - Protocols that manually configure pipette flow rates will be unaffected
+
+  - For a comparison between API Versions, see :ref:`defaults`
 
 
 Version 2.7
@@ -186,7 +192,7 @@ Version 2.7
 
   .. note::
 
-  This feature is still under development.
+      This feature is still under development.
 
 - Calling :py:meth:`.InstrumentContext.has_tip` will return whether a particular instrument
   has a tip attached or not.
@@ -194,10 +200,15 @@ Version 2.7
 
 Version 2.8
 +++++++++++
+
 - You can now pass in a list of volumes to distribute and consolidate. See :ref:`distribute-consolidate-volume-list` for more information.
-    - Passing in a zero volume to any :ref:`v2-complex-commands` will result in no actions taken for aspirate or dispense
+
+  - Passing in a zero volume to any :ref:`v2-complex-commands` will result in no actions taken for aspirate or dispense
+
 - :py:meth:`.Well.from_center_cartesian` can be used to find a point within a well using normalized distance from the center in each axis.
-    - **Note** that you will need to create a location object to use this function in a protocol. See :ref:`protocol-api-labware` for more information.
+
+  - **Note** that you will need to create a location object to use this function in a protocol. See :ref:`protocol-api-labware` for more information.
+
 - You can now pass in a blowout location to transfer, distribute, and consolidate 
   with the ``blowout_location`` parameter. See :py:meth:`.InstrumentContext.transfer` for more detail!
 
diff --git a/api/src/opentrons/hardware_control/api.py b/api/src/opentrons/hardware_control/api.py
index febf3154843..b09ac54bfbf 100644
--- a/api/src/opentrons/hardware_control/api.py
+++ b/api/src/opentrons/hardware_control/api.py
@@ -913,7 +913,7 @@ async def move_to(
 
         :param mount: The mount to move
         :param abs_position: The target absolute position in
-                             :ref:`protocol-api-deck-coords` to move the
+                             deck coordinates to move the
                              critical point to
         :param speed: An overall head speed to use during the move
         :param critical_point: The critical point to move. In most situations
diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py
index 26b44f0e2d0..f35fdde5407 100644
--- a/api/src/opentrons/protocol_api/instrument_context.py
+++ b/api/src/opentrons/protocol_api/instrument_context.py
@@ -1057,7 +1057,7 @@ def transfer(
         # TODO: ..trash or the original well.
         # TODO: What should happen if the user passes a non-first-row well
         # TODO: ..as src/dest *while using multichannel pipette?
-        r"""
+        """
         Transfer will move a volume of liquid from a source location(s)
         to a dest location(s). It is a higher-level command, incorporating
         other :py:class:`InstrumentContext` commands, like :py:meth:`aspirate`
@@ -1075,7 +1075,7 @@ def transfer(
                        will be aspirated.
         :param dest: A single well or a list of wells where liquid
                      will be dispensed to.
-        :param \**kwargs: See below
+        :param \\**kwargs: See below
 
         :Keyword Arguments:
 
@@ -1106,15 +1106,16 @@ def transfer(
                 - 'destination well': blowout excess liquid into destination
                    well
                 - 'trash': blowout excess liquid into the trash
-                If no `blowout_location` specified, no `disposal_volume`
+
+                If no ``blowout_location`` specified, no ``disposal_volume``
                 specified, and the pipette contains liquid,
-                a :py:meth:`blow_out` will occur into the source well
+                a :py:meth:`blow_out` will occur into the source well.
 
-                If no `blowout_location` specified and either
-                `disposal_volume` is specified or the pipette is empty,
-                a :py:meth:`blow_out` will occur into the trash
+                If no ``blowout_location`` specified and either
+                ``disposal_volume`` is specified or the pipette is empty,
+                a :py:meth:`blow_out` will occur into the trash.
 
-                If `blow_out` is set to `False`, this parameter will be ignored
+                If ``blow_out`` is set to ``False``, this parameter will be ignored.
 
             * *mix_before* (``tuple``) --
               The tuple, if specified, gives the amount of volume to
@@ -1255,7 +1256,7 @@ def move_to(
         :param location: The location to move to.
         :type location: :py:class:`.types.Location`
         :param force_direct: If set to true, move directly to destination
-                        without arc motion.
+                             without arc motion.
         :param minimum_z_height: When specified, this Z margin is able to raise
                                  (but never lower) the mid-arc height.
         :param speed: The speed at which to move. By default,
@@ -1264,7 +1265,7 @@ def move_to(
                       individual axis speeds, you can use
                       :py:attr:`.ProtocolContext.max_speeds`.
         :param publish: Whether a call to this function should publish to the
-        runlog or not.
+                        runlog or not.
         """
         from_loc = self._ctx.location_cache
         if not from_loc:
@@ -1530,25 +1531,23 @@ def pair_with(self, instrument: InstrumentContext) -> PairedInstrumentContext:
 
         :param instrument: The secondary instrument you wish to use
 
-        :raises UnsupportedInstrumentPairingError: If you try to pair
-        pipettes that are not currently supported together.
-        :returns: PairedInstrumentContext: This is the object you
-        will call commands on.
-
-        This function returns a :py:class:`PairedInstrumentContext`.
-        The building block commands are the same as an individual pipette's
-        building block commands found at :ref:`v2-atomic-commands`,
-        and when you want to move pipettes simultaneously you need to use the
-        :py:class:`PairedInstrumentContext`.
+        :raises UnsupportedInstrumentPairingError: If you try to pair pipettes that are
+                                                   not currently supported together.
 
+        :returns: A ``PairedInstrumentContext``. This is the object you will call
+                  commands on. The building block commands are the same as an individual
+                  pipette's building block commands found at :ref:`v2-atomic-commands`,
+                  and when you want to move pipettes simultaneously you need to use the
+                  ``PairedInstrumentContext``.
 
         Limitations:
+
         1. This function utilizes a "primary" and "secondary" pipette to make
-        positional decisions. The consequence of doing this is that all X & Y
-        positions are based on the primary pipette only.
+           positional decisions. The consequence of doing this is that all X & Y
+           positions are based on the primary pipette only.
         2. At this time, only pipettes of the same type are supported for
-        pipette pairing. This means that you cannot utilize a P1000 Single
-        channel and a P300 Single channel at the same time.
+           pipette pairing. This means that you cannot utilize a P1000 Single
+           channel and a P300 Single channel at the same time.
 
         .. code-block :: python
             :substitutions:
diff --git a/api/src/opentrons/protocol_api/labware.py b/api/src/opentrons/protocol_api/labware.py
index 4c43051d09d..08d3ab86d36 100644
--- a/api/src/opentrons/protocol_api/labware.py
+++ b/api/src/opentrons/protocol_api/labware.py
@@ -171,7 +171,7 @@ def from_center_cartesian(self, x: float, y: float, z: float) -> Point:
         Specifies an arbitrary point in deck coordinates based
         on percentages of the radius in each axis. For example, to specify the
         back-right corner of a well at 1/4 of the well depth from the bottom,
-        the call would be `from_center_cartesian(1, 1, -0.5)`.
+        the call would be ``from_center_cartesian(1, 1, -0.5)``.
 
         No checks are performed to ensure that the resulting position will be
         inside of the well.
@@ -183,8 +183,8 @@ def from_center_cartesian(self, x: float, y: float, z: float) -> Point:
         :param z: a float in the range [-1.0, 1.0] for a percentage of half of
             the height above/below the center
 
-        :return: a Point representing the specified location in absolute deck
-        coordinates
+        :return: a :py:class:`opentrons.types.Point` representing the specified
+                 location in absolute deck coordinates
         """
         return self._geometry.from_center_cartesian(x, y, z)
 
@@ -785,9 +785,9 @@ def select_tiprack_from_list_paired_pipettes(
     tipracks until it finds a well that is not empty.
 
     :return: A Tuple of the tiprack and well to move to. In this
-    instance the starting well is specific to the primary pipette.
+             instance the starting well is specific to the primary pipette.
     :raises TipSelectionError: if the starting tip specified
-    does not exist in the filtered tipracks.
+                               does not exist in the filtered tipracks.
     """
     try:
         first, rest = split_tipracks(tip_racks)
diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py
index 1f62bf9725f..837cd9b154f 100644
--- a/api/src/opentrons/protocol_api/protocol_context.py
+++ b/api/src/opentrons/protocol_api/protocol_context.py
@@ -406,7 +406,7 @@ def loaded_labwares(self) -> Dict[int, Labware]:
         .. note::
 
             If a module is present on the deck but no labware has been loaded
-            into it with :py:meth:`.ModuleContext.load_labware`, there will
+            into it with ``module.load_labware()``, there will
             be no entry for that slot in this value. That means you should not
             use ``loaded_labwares`` to determine if a slot is available or not,
             only to get a list of labwares. If you want a data structure of all
@@ -461,8 +461,11 @@ def load_module(
                               the non-full plate configuration, you must
                               pass in the key word value `semi`
         :type location: str or int or None
-        :returns ModuleContext: The loaded and initialized
-                                :py:class:`ModuleContext`.
+        :returns: The loaded and initialized module---a
+                  :py:class:`TemperatureModuleContext`,
+                  :py:class:`ThermocyclerContext`, or
+                  :py:class:`MagneticModuleContext`,
+                  depending on what you requested with ``module_name``.
         """
         if self._api_version < APIVersion(2, 4) and configuration:
             raise APIVersionError(
diff --git a/api/src/opentrons/simulate.py b/api/src/opentrons/simulate.py
index 16dd10ae7f1..8048e7eda25 100644
--- a/api/src/opentrons/simulate.py
+++ b/api/src/opentrons/simulate.py
@@ -288,8 +288,8 @@ def simulate(
         - ``logs``: Any log messages that occurred during execution of this
                     command, as a logging.LogRecord
 
-    :param file-like protocol_file: The protocol file to simulate.
-    :param str file_name: The name of the file
+    :param protocol_file: The protocol file to simulate.
+    :param file_name: The name of the file
     :param custom_labware_paths: A list of directories to search for custom
                                  labware, or None. Ignored if the apiv2 feature
                                  flag is not set. Loads valid labware from
@@ -313,14 +313,13 @@ def simulate(
                            occur during protocol simulation are best associated
                            with the actions in the protocol that cause them.
                            Default: ``False``
-    :type propagate_logs: bool
-    :param log_level: The level of logs to capture in the runlog. Default:
-                      ``'warning'``
-    :type log_level: 'debug', 'info', 'warning', or 'error'
+    :param log_level: The level of logs to capture in the runlog:
+                      ``"debug"``, ``"info"``, ``"warning"``, or ``"error"``.
+                      Defaults to ``'warning'``.
     :returns: A tuple of a run log for user output, and possibly the required
               data to write to a bundle to bundle this protocol. The bundle is
-              only emitted if bundling is allowed (see
-              :py:meth:`allow_bundling`)  and this is an unbundled Protocol API
+              only emitted if bundling is allowed
+              and this is an unbundled Protocol API
               v2 python protocol. In other cases it is None.
     """
     stack_logger = logging.getLogger("opentrons")