Various docs improvements (#16836)

hauntsaninja · web-flow · commit 1da0ebe5ab96 · 2024-01-29T21:27:19.000-08:00
Recommend `--disable-error-code=import-untyped`. It's probably strictly
better than `--ignore-missing-imports` for most users.

Remove the displaying error codes section, since it's on by default.

Some more advice and discoverability for "using mypy with an existing
codebase".
diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst
@@ -3,6 +3,10 @@
 The mypy configuration file
 ===========================
 
+Mypy is very configurable. This is most useful when introducing typing to
+an existing codebase. See :ref:`existing-code` for concrete advice for
+that situation.
+
 Mypy supports reading configuration settings from a file with the following precedence order:
 
     1. ``./mypy.ini``
diff --git a/docs/source/error_codes.rst b/docs/source/error_codes.rst
@@ -19,22 +19,6 @@ Most error codes are shared between multiple related error messages.
 Error codes may change in future mypy releases.
 
 
-
-Displaying error codes
-----------------------
-
-Error codes are displayed by default.  Use :option:`--hide-error-codes <mypy --hide-error-codes>`
-or config ``hide_error_codes = True`` to hide error codes. Error codes are shown inside square brackets:
-
-.. code-block:: text
-
-   $ mypy prog.py
-   prog.py:1: error: "str" has no attribute "trim"  [attr-defined]
-
-It's also possible to require error codes for ``type: ignore`` comments.
-See :ref:`ignore-without-code<code-ignore-without-code>` for more information.
-
-
 .. _silence-error-codes:
 
 Silencing errors based on error codes
@@ -121,3 +105,10 @@ Similar logic works for disabling error codes globally. If a given error code
 is a subcode of another one, it will be mentioned in the documentation for the narrower
 code. This hierarchy is not nested: there cannot be subcodes of other
 subcodes.
+
+
+Requiring error codes
+---------------------
+
+It's possible to require error codes be specified in ``type: ignore`` comments.
+See :ref:`ignore-without-code<code-ignore-without-code>` for more information.
diff --git a/docs/source/existing_code.rst b/docs/source/existing_code.rst
@@ -31,8 +31,8 @@ invocation to your codebase, or adding your mypy invocation to
 existing tools you use to run tests, like ``tox``.
 
 * Make sure everyone runs mypy with the same options. Checking a mypy
-  :ref:`configuration file <config-file>` into your codebase can help
-  with this.
+  :ref:`configuration file <config-file>` into your codebase is the
+  easiest way to do this.
 
 * Make sure everyone type checks the same set of files. See
   :ref:`specifying-code-to-be-checked` for details.
@@ -48,7 +48,7 @@ A simple CI script could look something like this:
 
 .. code-block:: text
 
-    python3 -m pip install mypy==0.971
+    python3 -m pip install mypy==1.8
     # Run your standardised mypy invocation, e.g.
     mypy my_project
     # This could also look like `scripts/run_mypy.sh`, `tox run -e mypy`, `make mypy`, etc
@@ -74,6 +74,11 @@ You could even invert this, by setting ``ignore_errors = True`` in your global
 config section and only enabling error reporting with ``ignore_errors = False``
 for the set of modules you are ready to type check.
 
+The per-module configuration that mypy's configuration file allows can be
+extremely useful. Many configuration options can be enabled or disabled
+only for specific modules. In particular, you can also enable or disable
+various error codes on a per-module basis, see :ref:`error-codes`.
+
 Fixing errors related to imports
 --------------------------------
 
@@ -89,7 +94,7 @@ that it can't find, that don't have types, or don't have stub files:
 Sometimes these can be fixed by installing the relevant packages or
 stub libraries in the environment you're running ``mypy`` in.
 
-See :ref:`ignore-missing-imports` for a complete reference on these errors
+See :ref:`fix-missing-imports` for a complete reference on these errors
 and the ways in which you can fix them.
 
 You'll likely find that you want to suppress all errors from importing
@@ -118,13 +123,15 @@ codebase, use a config like this:
    ignore_missing_imports = True
 
 If you get a large number of errors, you may want to ignore all errors
-about missing imports, for instance by setting :confval:`ignore_missing_imports`
-to true globally. This can hide errors later on, so we recommend avoiding this
+about missing imports, for instance by setting
+:option:`--disable-error-code=import-untyped <mypy --ignore-missing-imports>`.
+or setting :confval:`ignore_missing_imports` to true globally.
+This can hide errors later on, so we recommend avoiding this
 if possible.
 
 Finally, mypy allows fine-grained control over specific import following
 behaviour. It's very easy to silently shoot yourself in the foot when playing
-around with these, so it's mostly recommended as a last resort. For more
+around with these, so this should be a last resort. For more
 details, look :ref:`here <follow-imports>`.
 
 Prioritise annotating widely imported modules
diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst
@@ -305,16 +305,20 @@ not catch errors in its use.
     The ``.*`` after ``foobar`` will ignore imports of ``foobar`` modules
     and subpackages in addition to the ``foobar`` top-level package namespace.
 
-3.  To suppress *all* missing import errors for *all* libraries in your codebase,
-    invoke mypy with 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::
+3.  To suppress *all* missing import errors for *all* untyped libraries
+    in your codebase, use :option:`--disable-error-code=import-untyped <mypy --ignore-missing-imports>`.
+    See :ref:`code-import-untyped` for more details on this error code.
+
+    You can also set :confval:`disable_error_code`, like so::
 
         [mypy]
-        ignore_missing_imports = True
+        disable_error_code = import-untyped
+
 
-    We recommend using this approach only as a last resort: it's equivalent
+    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.
 
 
