Add note about Sphinx name resolution for Python objects.

Almost nobody knows that Sphinx normally pays no attention to your
import statements.

Author: TallJimbo

restructuredtext/style.rst

@@ -356,6 +356,38 @@ Objects can be referenced with these roles:
 - ``:py:data:`pkg.mod.VARIABLE``` to reference a module-level variable ``VARIABLE`` in ``pkg.mod``.
 - ``:py:const:`pkg.mod.CONSTANT``` to reference a module-level *constant* ``CONSTANT`` in ``pkg.mod``.
 
+.. note::
+   Types in docstrings do *not* respect imports in the file, and instead are resolved using `Sphinx's own target-resolution rules <https://www.sphinx-doc.org/en/master/usage/domains/python.html#target-resolution>`__.
+   In other words,
+
+   .. code-block::
+
+      from collections.abc import Sequence
+
+      def run_stuff(stuff):
+          """Run some stuff.
+
+          Parameters
+          ----------
+          stuff : `Sequence` [`str`]
+              Stuff to run.
+
+   does not work, but
+
+   .. code-block::
+
+      from collections.abc import Sequence
+
+      def run_stuff(stuff):
+          """Run some stuff.
+
+          Parameters
+          ----------
+          stuff : `~collections.abc.Sequence` [`str`]
+              Stuff to run.
+
+   does.  See the link above for how to make relative links to types; the syntax is not the same as Python's, and it operates on the documentation hierarchy, not the module hierarchy.
+
 Namespace resolution
 """"""""""""""""""""