Document stub-only packages incompatibility with MYPYPATH

docs/source/installed_packages.rst

@@ -30,6 +30,13 @@ imports, namespace packages, and custom import hooks.
 If you do not want to use typed packages, use the ``--no-site-packages`` flag
 to disable searching.
 
+Note that stub-only packages (defined in
+`PEP 561 <https://www.python.org/dev/peps/pep-0561/#stub-only-packages>`_)
+cannot be used with ``MYPYPATH``. If you want mypy to find the package, it must
+be installed. For a package ``foo``, the name of the stub-only package
+(``foo-stubs``) is not a legal package name, so mypy will not find it, unless
+it is installed.
+
 Making PEP 561 compatible packages
 **********************************
 

docs/source/running_mypy.rst

@@ -304,6 +304,11 @@ This is computed from the following items:
 - The relevant directories of the
   `typeshed <https://github.com/python/typeshed>`_ repo.
 
+.. note::
+
+    You cannot point to a PEP 561 package via the MYPYPATH, it must be
+    installed (see :ref:`PEP 561 support <installed-packages>`)
+
 For sources given on the command line, the path is adjusted by crawling
 up from the given file or package to the nearest directory that does not
 contain an ``__init__.py`` or ``__init__.pyi`` file.

docs/source/stubs.rst

@@ -25,7 +25,10 @@ Here is an overview of how to create a stub file:
     $ export MYPYPATH=~/work/myproject/stubs
 
 Use the normal Python file name conventions for modules, e.g. ``csv.pyi``
-for module ``csv``. Use a subdirectory with ``__init__.pyi`` for packages.
+for module ``csv``. Use a subdirectory with ``__init__.pyi`` for packages. Note
+that `PEP 561 <https://www.python.org/dev/peps/pep-0561/>`_ stub-only packages
+must be installed, and may not be pointed at through the ``MYPYPATH``
+(see :ref:`PEP 561 support <installed-packages>`).
 
 If a directory contains both a ``.py`` and a ``.pyi`` file for the
 same module, the ``.pyi`` file takes precedence. This way you can