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

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

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