Document per-module follow_imports more explicitly

Helps with python#10842, python#10820 and others

There have been a number of issues recently where having this spelt out
a little more explicitly would help users. The introduction of
`--exclude` also (pretty understandably) confuses users who don't realise
mypy's recursive file discovery is a little separate from its dogged
import following.

I think it could be reasonable to change mypy's behaviour so that
exclude also implies follow_imports=skip (or maybe silent), but it might
be a little finnicky (one is a regex on filenames, the other is patterns
on fully qualified module names). I'm also just wary of attempting to
change this - import following configuration is probably one of the
more complicated and poorly understood parts of mypy's UX - so passing
on that for now.

docs/source/command_line.rst

@@ -60,10 +60,16 @@ for full details, see :ref:`running-mypy`.
     directories with a given name by e.g. ``--exclude /build/`` or
     those matching a subpath with ``--exclude /project/vendor/``.
 
-    Note that this flag only affects recursive discovery, that is, when mypy is
-    discovering files within a directory tree or submodules of a package to
-    check. If you pass a file or module explicitly it will still be checked. For
-    instance, ``mypy --exclude '/setup.py$' but_still_check/setup.py``.
+    Note that this flag only affects recursive directory tree discovery, that
+    is, when mypy is discovering files within a directory tree or submodules of
+    a package to check. If you pass a file or module explicitly it will still be
+    checked. For instance, ``mypy --exclude '/setup.py$'
+    but_still_check/setup.py``.
+
+    In particular, ``--exclude`` does not affect mypy's :ref:`import following
+    <follow-imports>`. You can use a per-module :confval:`follow_imports` config
+    option to additionally avoid mypy from following imports and checking code
+    you do not wish to be checked.
 
     Note that mypy will never recursively discover files and directories named
     "site-packages", "node_modules" or "__pycache__", or those whose name starts

docs/source/config_file.rst

@@ -254,6 +254,10 @@ section of the command line docs.
     ``error``.  For explanations see the discussion for the
     :option:`--follow-imports <mypy --follow-imports>` command line flag.
 
+    Using this option in a per-module section (potentially with a wildcard,
+    as described at the top of this page) is a good way to prevent mypy from
+    checking portions of your code.
+
     If this option is used in a per-module section, the module name should
     match the name of the *imported* module, not the module containing the
     import statement.
@@ -924,10 +928,10 @@ Instead of using a ``mypy.ini`` file, a ``pyproject.toml`` file (as specified by
 
   * Boolean values should be all lower case
 
-Please see the `TOML Documentation`_ for more details and information on 
+Please see the `TOML Documentation`_ for more details and information on
 what is allowed in a ``toml`` file. See `PEP 518`_ for more information on the layout
 and structure of the ``pyproject.toml`` file.
-  
+
 Example ``pyproject.toml``
 **************************
 

docs/source/running_mypy.rst

@@ -384,6 +384,10 @@ We do not recommend using ``skip`` unless you know what you are doing:
 while this option can be quite powerful, it can also cause many
 hard-to-debug errors.
 
+Adjusting import following behaviour is often most useful when restricted to
+specific modules. This can be accomplished by setting a per-module
+:confval:`follow_imports` config option.
+
 
 .. _mapping-paths-to-modules: