Warn about --follow-untyped-imports (#18249)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Marc Mueller <30130371+cdce8p@users.noreply.github.com>

docs/source/command_line.rst

@@ -168,7 +168,14 @@ imports.
 
 .. option:: --follow-untyped-imports
 
-    This flag makes mypy analyze imports without stubs or a py.typed marker.
+    This flag makes mypy analyze imports from installed packages even if
+    missing a :ref:`py.typed marker or stubs <installed-packages>`.
+
+    .. warning::
+
+        Note that analyzing all unannotated modules might result in issues
+        when analyzing code not designed to be type checked and may significantly
+        increase how long mypy takes to run.
 
 .. option:: --follow-imports {normal,silent,skip,error}
 

docs/source/config_file.rst

@@ -320,12 +320,18 @@ section of the command line docs.
     :type: boolean
     :default: False
 
-    Typechecks imports from modules that do not have stubs or a py.typed marker.
+    Makes mypy analyze imports from installed packages even if missing a
+    :ref:`py.typed marker or stubs <installed-packages>`.
 
     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. Note that scanning all unannotated modules might
-    significantly increase the runtime of your mypy calls.
+    import statement.
+
+    .. warning::
+
+        Note that analyzing all unannotated modules might result in issues
+        when analyzing code not designed to be type checked and may significantly
+        increase how long mypy takes to run.
 
 .. confval:: follow_imports
 

docs/source/running_mypy.rst

@@ -277,6 +277,25 @@ If you are getting this error, try to obtain type hints for the library you're u
     to the library -- see our documentation on creating
     :ref:`PEP 561 compliant packages <installed-packages>`.
 
+4.  Force mypy to analyze the library as best as it can (as if the library provided
+    a ``py.typed`` file), despite it likely missing any type annotations. In general,
+    the quality of type checking will be poor and mypy may have issues when
+    analyzing code not designed to be type checked.
+
+    You can do this via setting the
+    :option:`--follow-untyped-imports <mypy --follow-untyped-imports>`
+    command line flag or :confval:`follow_untyped_imports` config file option to True.
+    This option can be specified on a per-module basis as well::
+
+        # mypy.ini
+        [mypy-untyped_package.*]
+        follow_untyped_imports = True
+
+        # pyproject.toml
+        [[tool.mypy.overrides]]
+        module = ["untyped_package.*"]
+        follow_untyped_imports = true
+
 If you are unable to find any existing type hints nor have time to write your
 own, you can instead *suppress* the errors.
 
@@ -295,9 +314,15 @@ not catch errors in its use.
     all import errors associated with that library and that library alone by
     adding the following section to your config file::
 
+        # mypy.ini
         [mypy-foobar.*]
         ignore_missing_imports = True
 
+        # pyproject.toml
+        [[tool.mypy.overrides]]
+        module = ["foobar.*"]
+        ignore_missing_imports = true
+
     Note: this option is equivalent to adding a ``# type: ignore`` to every
     import of ``foobar`` in your codebase. For more information, see the
     documentation about configuring
@@ -311,22 +336,20 @@ not catch errors in its use.
 
     You can also set :confval:`disable_error_code`, like so::
 
+        # mypy.ini
         [mypy]
         disable_error_code = import-untyped
 
+        # pyproject.toml
+        [tool.mypy]
+        disable_error_code = ["import-untyped"]
 
     You can also set the :option:`--ignore-missing-imports <mypy --ignore-missing-imports>`
     command line flag or set the :confval:`ignore_missing_imports` config file
     option to True in the *global* section of your mypy config file. We
     recommend avoiding ``--ignore-missing-imports`` if possible: it's equivalent
     to adding a ``# type: ignore`` to all unresolved imports in your codebase.
 
-4.  To make mypy typecheck imports from modules without stubs or a py.typed
-    marker, you can set the :option:`--follow-untyped-imports <mypy --follow-untyped-imports>`
-    command line flag or set the :confval:`follow_untyped_imports` config file option to True,
-    either in the global section of your mypy config file, or individually on a
-    per-module basis.
-
 
 Library stubs not installed
 ---------------------------