From 9b327d12bc3b57cc30ed76dcd3e07a3674da17a2 Mon Sep 17 00:00:00 2001
From: Ivan Levkivskyi <levkivskyi@gmail.com>
Date: Wed, 14 Jun 2023 14:35:28 +0100
Subject: [PATCH] Use consistent anchors for error codes (#15435)

Fixes #15431

After this PR one will be able to easily find documentation for given
error code using
`https://mypy.readthedocs.io/en/stable/_refs.html#code-{code as reported
by mypy}`, for example
`https://mypy.readthedocs.io/en/stable/_refs.html#code-attr-defined`.
---
 docs/source/error_code_list.rst  | 76 ++++++++++++++++++++++++++++++++
 docs/source/error_code_list2.rst | 29 +++++++++++-
 docs/source/error_codes.rst      |  2 +-
 docs/source/html_builder.py      | 19 ++++++++
 4 files changed, 123 insertions(+), 3 deletions(-)

diff --git a/docs/source/error_code_list.rst b/docs/source/error_code_list.rst
index 54dc31f2cfcb..1654c5910f98 100644
--- a/docs/source/error_code_list.rst
+++ b/docs/source/error_code_list.rst
@@ -8,6 +8,8 @@ with default options. See :ref:`error-codes` for general documentation
 about error codes. :ref:`error-codes-optional` documents additional
 error codes that you can enable.
 
+.. _code-attr-defined:
+
 Check that attribute exists [attr-defined]
 ------------------------------------------
 
@@ -43,6 +45,8 @@ A reference to a missing attribute is given the ``Any`` type. In the
 above example, the type of ``non_existent`` will be ``Any``, which can
 be important if you silence the error.
 
+.. _code-union-attr:
+
 Check that attribute exists in each union item [union-attr]
 -----------------------------------------------------------
 
@@ -75,6 +79,8 @@ You can often work around these errors by using ``assert isinstance(obj, ClassNa
 or ``assert obj is not None`` to tell mypy that you know that the type is more specific
 than what mypy thinks.
 
+.. _code-name-defined:
+
 Check that name is defined [name-defined]
 -----------------------------------------
 
@@ -89,6 +95,7 @@ This example accidentally calls ``sort()`` instead of :py:func:`sorted`:
 
     x = sort([3, 2, 4])  # Error: Name "sort" is not defined  [name-defined]
 
+.. _code-used-before-def:
 
 Check that a variable is not used before it's defined [used-before-def]
 -----------------------------------------------------------------------
@@ -105,6 +112,7 @@ Example:
     print(x)  # Error: Name "x" is used before definition [used-before-def]
     x = 123
 
+.. _code-call-arg:
 
 Check arguments in calls [call-arg]
 -----------------------------------
@@ -124,6 +132,8 @@ Example:
     greet('jack')  # OK
     greet('jill', 'jack')  # Error: Too many arguments for "greet"  [call-arg]
 
+.. _code-arg-type:
+
 Check argument types [arg-type]
 -------------------------------
 
@@ -144,6 +154,8 @@ Example:
     #        expected "list[int]"  [arg-type]
     print(first(t))
 
+.. _code-call-overload:
+
 Check calls to overloaded functions [call-overload]
 ---------------------------------------------------
 
@@ -175,6 +187,8 @@ Example:
    # Error: No overload variant of "inc_maybe" matches argument type "float"  [call-overload]
    inc_maybe(1.2)
 
+.. _code-valid-type:
+
 Check validity of types [valid-type]
 ------------------------------------
 
@@ -207,6 +221,8 @@ You can use :py:data:`~typing.Callable` as the type for callable objects:
         for x in objs:
             f(x)
 
+.. _code-var-annotated:
+
 Require annotation if variable type is unclear [var-annotated]
 --------------------------------------------------------------
 
@@ -239,6 +255,8 @@ To address this, we add an explicit annotation:
 
    reveal_type(Bundle().items)  # list[str]
 
+.. _code-override:
+
 Check validity of overrides [override]
 --------------------------------------
 
@@ -275,6 +293,8 @@ Example:
                   arg: bool) -> int:
            ...
 
+.. _code-return:
+
 Check that function returns a value [return]
 --------------------------------------------
 
@@ -303,6 +323,8 @@ Example:
         else:
             raise ValueError('not defined for zero')
 
+.. _code-return-value:
+
 Check that return value is compatible [return-value]
 ----------------------------------------------------
 
@@ -317,6 +339,8 @@ Example:
        # Error: Incompatible return value type (got "int", expected "str")  [return-value]
        return x + 1
 
+.. _code-assignment:
+
 Check types in assignment statement [assignment]
 ------------------------------------------------
 
@@ -339,6 +363,8 @@ Example:
     #        variable has type "str")  [assignment]
     r.name = 5
 
+.. _code-method-assign:
+
 Check that assignment target is not a method [method-assign]
 ------------------------------------------------------------
 
@@ -368,6 +394,8 @@ so only the second assignment will still generate an error.
 
     This error code is a subcode of the more general ``[assignment]`` code.
 
+.. _code-type-var:
+
 Check type variable values [type-var]
 -------------------------------------
 
@@ -390,6 +418,8 @@ Example:
     # Error: Value of type variable "T1" of "add" cannot be "str"  [type-var]
     add('x', 'y')
 
+.. _code-operator:
+
 Check uses of various operators [operator]
 ------------------------------------------
 
@@ -404,6 +434,8 @@ Example:
    # Error: Unsupported operand types for + ("int" and "str")  [operator]
    1 + 'x'
 
+.. _code-index:
+
 Check indexing operations [index]
 ---------------------------------
 
@@ -425,6 +457,8 @@ Example:
    # Error: Invalid index type "bytes" for "dict[str, int]"; expected type "str"  [index]
    a[b'x'] = 4
 
+.. _code-list-item:
+
 Check list items [list-item]
 ----------------------------
 
@@ -439,6 +473,8 @@ Example:
     # Error: List item 0 has incompatible type "int"; expected "str"  [list-item]
     a: list[str] = [0]
 
+.. _code-dict-item:
+
 Check dict items [dict-item]
 ----------------------------
 
@@ -453,6 +489,8 @@ Example:
     # Error: Dict entry 0 has incompatible type "str": "str"; expected "str": "int"  [dict-item]
     d: dict[str, int] = {'key': 'value'}
 
+.. _code-typeddict-item:
+
 Check TypedDict items [typeddict-item]
 --------------------------------------
 
@@ -477,6 +515,8 @@ Example:
     #        TypedDict item "x" has type "int")  [typeddict-item]
     p: Point = {'x': 1.2, 'y': 4}
 
+.. _code-typeddict-unknown-key:
+
 Check TypedDict Keys [typeddict-unknown-key]
 --------------------------------------------
 
@@ -533,6 +573,8 @@ runtime:
 
     This error code is a subcode of the wider ``[typeddict-item]`` code.
 
+.. _code-has-type:
+
 Check that type of target is known [has-type]
 ---------------------------------------------
 
@@ -572,6 +614,8 @@ the issue:
        def set_y(self) -> None:
            self.y: int = self.x  # Added annotation here
 
+.. _code-import:
+
 Check that import target can be found [import]
 ----------------------------------------------
 
@@ -587,6 +631,8 @@ Example:
 
 See :ref:`ignore-missing-imports` for how to work around these errors.
 
+.. _code-no-redef:
+
 Check that each name is defined once [no-redef]
 -----------------------------------------------
 
@@ -613,6 +659,8 @@ Example:
    #        (the first definition wins!)
    A('x')
 
+.. _code-func-returns-value:
+
 Check that called function returns a value [func-returns-value]
 ---------------------------------------------------------------
 
@@ -635,6 +683,8 @@ returns ``None``:
    if f():
         print("not false")
 
+.. _code-abstract:
+
 Check instantiation of abstract classes [abstract]
 --------------------------------------------------
 
@@ -666,6 +716,8 @@ Example:
     # Error: Cannot instantiate abstract class "Thing" with abstract attribute "save"  [abstract]
     t = Thing()
 
+.. _code-type-abstract:
+
 Safe handling of abstract type object types [type-abstract]
 -----------------------------------------------------------
 
@@ -692,6 +744,8 @@ Example:
    # Error: Only concrete class can be given where "Type[Config]" is expected [type-abstract]
    make_many(Config, 5)
 
+.. _code-safe-super:
+
 Check that call to an abstract method via super is valid [safe-super]
 ---------------------------------------------------------------------
 
@@ -714,6 +768,8 @@ will cause runtime errors, so mypy prevents you from doing so:
 Mypy considers the following as trivial bodies: a ``pass`` statement, a literal
 ellipsis ``...``, a docstring, and a ``raise NotImplementedError`` statement.
 
+.. _code-valid-newtype:
+
 Check the target of NewType [valid-newtype]
 -------------------------------------------
 
@@ -738,6 +794,8 @@ To work around the issue, you can either give mypy access to the sources
 for ``acme`` or create a stub file for the module.  See :ref:`ignore-missing-imports`
 for more information.
 
+.. _code-exit-return:
+
 Check the return type of __exit__ [exit-return]
 -----------------------------------------------
 
@@ -794,6 +852,8 @@ You can also use ``None``:
        def __exit__(self, exc, value, tb) -> None:  # Also OK
            print('exit')
 
+.. _code-name-match:
+
 Check that naming is consistent [name-match]
 --------------------------------------------
 
@@ -807,6 +867,8 @@ consistently when using the call-based syntax. Example:
     # Error: First argument to namedtuple() should be "Point2D", not "Point"
     Point2D = NamedTuple("Point", [("x", int), ("y", int)])
 
+.. _code-literal-required:
+
 Check that literal is used where expected [literal-required]
 ------------------------------------------------------------
 
@@ -836,6 +898,8 @@ or ``Literal`` variables. Example:
        #   expected one of ("x", "y")  [literal-required]
        p[key]
 
+.. _code-no-overload-impl:
+
 Check that overloaded functions have an implementation [no-overload-impl]
 -------------------------------------------------------------------------
 
@@ -858,6 +922,8 @@ implementation.
    def func(value):
        pass  # actual implementation
 
+.. _code-unused-coroutine:
+
 Check that coroutine return value is used [unused-coroutine]
 ------------------------------------------------------------
 
@@ -881,6 +947,8 @@ otherwise unused variable:
 
        _ = f()  # No error
 
+.. _code-assert-type:
+
 Check types in assert_type [assert-type]
 ----------------------------------------
 
@@ -895,6 +963,8 @@ the provided type.
 
    assert_type([1], list[str])  # Error
 
+.. _code-truthy-function:
+
 Check that function isn't used in boolean context [truthy-function]
 -------------------------------------------------------------------
 
@@ -908,6 +978,8 @@ Functions will always evaluate to true in boolean contexts.
     if f:  # Error: Function "Callable[[], Any]" could always be true in boolean context  [truthy-function]
         pass
 
+.. _code-str-bytes-safe:
+
 Check for implicit bytes coercions [str-bytes-safe]
 -------------------------------------------------------------------
 
@@ -926,6 +998,8 @@ Warn about cases where a bytes object may be converted to a string in an unexpec
     print(f"The alphabet starts with {b!r}")  # The alphabet starts with b'abc'
     print(f"The alphabet starts with {b.decode('utf-8')}")  # The alphabet starts with abc
 
+.. _code-syntax:
+
 Report syntax errors [syntax]
 -----------------------------
 
@@ -933,6 +1007,8 @@ If the code being checked is not syntactically valid, mypy issues a
 syntax error. Most, but not all, syntax errors are *blocking errors*:
 they can't be ignored with a ``# type: ignore`` comment.
 
+.. _code-misc:
+
 Miscellaneous checks [misc]
 ---------------------------
 
diff --git a/docs/source/error_code_list2.rst b/docs/source/error_code_list2.rst
index 8be2ac0b1d73..11f463f93018 100644
--- a/docs/source/error_code_list2.rst
+++ b/docs/source/error_code_list2.rst
@@ -15,6 +15,8 @@ error codes that are enabled by default.
    options by using a :ref:`configuration file <config-file>` or
    :ref:`command-line options <command-line>`.
 
+.. _code-type-arg:
+
 Check that type arguments exist [type-arg]
 ------------------------------------------
 
@@ -34,6 +36,8 @@ Example:
     def remove_dups(items: list) -> list:
         ...
 
+.. _code-no-untyped-def:
+
 Check that every function has an annotation [no-untyped-def]
 ------------------------------------------------------------
 
@@ -62,6 +66,8 @@ Example:
          def __init__(self) -> None:
              self.value = 0
 
+.. _code-redundant-cast:
+
 Check that cast is not redundant [redundant-cast]
 -------------------------------------------------
 
@@ -82,6 +88,8 @@ Example:
         # Error: Redundant cast to "int"  [redundant-cast]
         return cast(int, x)
 
+.. _code-redundant-self:
+
 Check that methods do not have redundant Self annotations [redundant-self]
 --------------------------------------------------------------------------
 
@@ -104,6 +112,8 @@ Example:
        def copy(self: Self) -> Self:
            return type(self)()
 
+.. _code-comparison-overlap:
+
 Check that comparisons are overlapping [comparison-overlap]
 -----------------------------------------------------------
 
@@ -135,6 +145,8 @@ literal:
     def is_magic(x: bytes) -> bool:
         return x == b'magic'  # OK
 
+.. _code-no-untyped-call:
+
 Check that no untyped functions are called [no-untyped-call]
 ------------------------------------------------------------
 
@@ -154,6 +166,7 @@ Example:
     def bad():
         ...
 
+.. _code-no-any-return:
 
 Check that function does not return Any value [no-any-return]
 -------------------------------------------------------------
@@ -175,6 +188,8 @@ Example:
         # Error: Returning Any from function declared to return "str"  [no-any-return]
         return fields(x)[0]
 
+.. _code-no-any-unimported:
+
 Check that types have no Any components due to missing imports [no-any-unimported]
 ----------------------------------------------------------------------------------
 
@@ -195,6 +210,8 @@ that ``Cat`` falls back to ``Any`` in a type annotation:
     def feed(cat: Cat) -> None:
         ...
 
+.. _code-unreachable:
+
 Check that statement or expression is unreachable [unreachable]
 ---------------------------------------------------------------
 
@@ -214,6 +231,8 @@ incorrect control flow or conditional checks that are accidentally always true o
         # Error: Statement is unreachable  [unreachable]
         print('unreachable')
 
+.. _code-redundant-expr:
+
 Check that expression is redundant [redundant-expr]
 ---------------------------------------------------
 
@@ -236,6 +255,8 @@ mypy generates an error if it thinks that an expression is redundant.
         [i for i in range(x) if isinstance(i, int)]
 
 
+.. _code-truthy-bool:
+
 Check that expression is not implicitly true in boolean context [truthy-bool]
 -----------------------------------------------------------------------------
 
@@ -259,6 +280,7 @@ Using an iterable value in a boolean context has a separate error code
     if foo:
          ...
 
+.. _code-truthy-iterable:
 
 Check that iterable is not implicitly true in boolean context [truthy-iterable]
 -------------------------------------------------------------------------------
@@ -286,8 +308,7 @@ items`` check is actually valid. If that is the case, it is
 recommended to annotate ``items`` as ``Collection[int]`` instead of
 ``Iterable[int]``.
 
-
-.. _ignore-without-code:
+.. _code-ignore-without-code:
 
 Check that ``# type: ignore`` include an error code [ignore-without-code]
 -------------------------------------------------------------------------
@@ -319,6 +340,8 @@ Example:
     # Error: "Foo" has no attribute "nme"; maybe "name"?
     f.nme = 42  # type: ignore[assignment]
 
+.. _code-unused-awaitable:
+
 Check that awaitable return value is used [unused-awaitable]
 ------------------------------------------------------------
 
@@ -348,6 +371,8 @@ silence the error:
     async def g() -> None:
         _ = asyncio.create_task(f())  # No error
 
+.. _code-unused-ignore:
+
 Check that ``# type: ignore`` comment is used [unused-ignore]
 -------------------------------------------------------------
 
diff --git a/docs/source/error_codes.rst b/docs/source/error_codes.rst
index c8a2728b5697..65ae0e5816e8 100644
--- a/docs/source/error_codes.rst
+++ b/docs/source/error_codes.rst
@@ -32,7 +32,7 @@ or config ``hide_error_codes = True`` to hide error codes. Error codes are shown
    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<ignore-without-code>` for more information.
+See :ref:`ignore-without-code<code-ignore-without-code>` for more information.
 
 
 .. _silence-error-codes:
diff --git a/docs/source/html_builder.py b/docs/source/html_builder.py
index 49d58dda12ec..efe1fcaa48fa 100644
--- a/docs/source/html_builder.py
+++ b/docs/source/html_builder.py
@@ -9,6 +9,8 @@
 from sphinx.application import Sphinx
 from sphinx.builders.html import StandaloneHTMLBuilder
 
+from mypy.errorcodes import error_codes
+
 
 class MypyHTMLBuilder(StandaloneHTMLBuilder):
     def __init__(self, app: Sphinx) -> None:
@@ -20,6 +22,23 @@ def write_doc(self, docname: str, doctree: document) -> None:
         self._ref_to_doc.update({_id: docname for _id in doctree.ids})
 
     def _write_ref_redirector(self) -> None:
+        known_missing = {
+            # TODO: fix these before next release
+            "annotation-unchecked",
+            "empty-body",
+            "possibly-undefined",
+            "str-format",
+            "top-level-await",
+        }
+        missing_error_codes = {
+            c
+            for c in error_codes
+            if f"code-{c}" not in self._ref_to_doc and c not in known_missing
+        }
+        if missing_error_codes:
+            raise ValueError(
+                f"Some error codes are not documented: {', '.join(sorted(missing_error_codes))}"
+            )
         p = Path(self.outdir) / "_refs.html"
         data = f"""
         <html>