Clarify docs surrounding install-types (#14003)

See #13681

More clearly point out the speed cost and the alternative of installing
stub packages directly

Author: hauntsaninja

docs/source/running_mypy.rst

@@ -322,34 +322,27 @@ the library, you will get a message like this:
     main.py:1: note: Hint: "python3 -m pip install types-PyYAML"
     main.py:1: note: (or run "mypy --install-types" to install all missing stub packages)
 
-You can resolve the issue by running the suggested pip command or
-commands. Alternatively, you can use :option:`--install-types <mypy
---install-types>` to install all known missing stubs:
+You can resolve the issue by running the suggested pip commands.
+If you're running mypy in CI, you can ensure the presence of any stub packages
+you need the same as you would any other test dependency, e.g. by adding them to
+the appropriate ``requirements.txt`` file.
 
-.. code-block:: text
-
-    mypy --install-types
-
-This installs any stub packages that were suggested in the previous
-mypy run. You can also use your normal mypy command line with the
-extra :option:`--install-types <mypy --install-types>` option to
-install missing stubs at the end of the run (if any were found).
-
-Use :option:`--install-types <mypy --install-types>` with
-:option:`--non-interactive <mypy --non-interactive>`  to install all suggested
-stub packages without asking for confirmation, *and* type check your
-code, in a single command:
+Alternatively, add the :option:`--install-types <mypy --install-types>`
+to your mypy command to install all known missing stubs:
 
 .. code-block:: text
 
-   mypy --install-types --non-interactive src/
+    mypy --install-types
 
-This can be useful in Continuous Integration jobs if you'd prefer not
-to manage stub packages manually. This is somewhat slower than
-explicitly installing stubs before running mypy, since it may type
-check your code twice -- the first time to find the missing stubs, and
+This is slower than explicitly installing stubs, since if effectively
+runs mypy twice -- the first time to find the missing stubs, and
 the second time to type check your code properly after mypy has
-installed the stubs.
+installed the stubs. It also can make controlling stub versions harder,
+resulting in less reproducible type checking.
+
+By default, :option:`--install-types <mypy --install-types>` shows a confirmation prompt.
+Use :option:`--non-interactive <mypy --non-interactive>` to install all suggested
+stub packages without asking for confirmation *and* type check your code:
 
 If you've already installed the relevant third-party libraries in an environment
 other than the one mypy is running in, you can use :option:`--python-executable
@@ -394,15 +387,6 @@ this error, try:
     you must run ``mypy ~/foo-project/src`` (or set the ``MYPYPATH`` to
     ``~/foo-project/src``.
 
-In some rare cases, you may get the "Cannot find implementation or library
-stub for module" error even when the module is installed in your system.
-This can happen when the module is both missing type hints and is installed
-on your system in an unconventional way.
-
-In this case, follow the steps above on how to handle
-:ref:`missing type hints in third party libraries <missing-type-hints-for-third-party-library>`.
-
-
 .. _finding-imports:
 
 How imports are found