Add docs for --namespace-packages (#5749)

Follow-up for #5691. Should be cherry-picked into the release (#5741). Fixes #5757.

Author: gvanrossum

docs/source/command_line.rst

@@ -72,6 +72,24 @@ Import discovery
 The following flags customize how exactly mypy discovers and follows
 imports.
 
+``--namespace-packages``
+    This flag enables import discovery to use namespace packages (see
+    `PEP 420`_).  In particular, this allows discovery of imported
+    packages that don't have an ``__init__.py`` (or ``__init__.pyi``)
+    file.
+
+    Namespace packages are found (using the PEP 420 rules, which
+    prefers "classic" packages over namespace packages) along the
+    module search path -- this is primarily set from the source files
+    passed on the command line, the ``MYPYPATH`` environment variable,
+    and the :ref:`mypy_path config option
+    <config-file-import-discovery-global>`.
+
+    Note that this only affects import discovery -- for modules and
+    packages explicitly passed on the command line, mypy still
+    searches for ``__init__.py[i]`` files in order to determine the
+    fully-qualified module/package name.
+
 ``--ignore-missing-imports``
     This flag makes mypy ignore all missing imports. It is equivalent
     to adding ``# type: ignore`` comments to all unresolved imports
@@ -570,6 +588,8 @@ Miscellaneous
     have many scripts that import a large package, the behavior enabled
     by this flag is often more convenient.)
 
+.. _PEP 420: https://www.python.org/dev/peps/pep-0420/
+
 .. _PEP 561: https://www.python.org/dev/peps/pep-0561/
 
 .. _lxml: https://pypi.org/project/lxml/

docs/source/config_file.rst

@@ -304,6 +304,10 @@ Note: this section describes only global-only import discovery options. See abov
 a list of import discovery options that may be used 
 :ref:`both per-module and globally <config-file-import-discovery-per-module>`.
 
+``namespace_packages`` (bool, default False)
+    Enables PEP 420 style namespace packages.  See :ref:`the
+    corresponding flag <import-discovery>` for more information.
+
 ``python_executable`` (string)
     Specifies the path to the Python executable to inspect to collect
     a list of available :ref:`PEP 561 packages <installed-packages>`. Defaults to