revisited error_code{s,_list,_list2}.rst, extending_mypy.rst, faq.rst, final_attrs.rst

Signed-off-by: Oleg Höfling <[email protected]>

Author: hoefling

docs/source/error_code_list.rst

@@ -83,7 +83,7 @@ definition in an active scope, such as an assignment, function
 definition or an import. This can catch missing definitions, missing
 imports, and typos.
 
-This example accidentally calls ``sort()`` instead of ``sorted()``:
+This example accidentally calls ``sort()`` instead of :py:func:`sorted`:
 
 .. code-block:: python
 
@@ -181,7 +181,7 @@ This example incorrectly uses the function ``log`` as a type:
        for x in objs:
            f(x)
 
-You can use ``Callable`` as the type for callable objects:
+You can use :py:data:`~typing.Callable` as the type for callable objects:
 
 .. code-block:: python
 
@@ -415,11 +415,11 @@ Example:
     # Error: Dict entry 0 has incompatible type "str": "str"; expected "str": "int"  [dict-item]
     d: Dict[str, int] = {'key': 'value'}
 
-Check TypedDict items [typeddict-item]
---------------------------------------
+Check ``TypedDict`` items [typeddict-item]
+------------------------------------------
 
-When constructing a TypedDict object, mypy checks that each key and value is compatible
-with the TypedDict type that is inferred from the surrounding context.
+When constructing a ``TypedDict`` object, mypy checks that each key and value is compatible
+with the ``TypedDict`` type that is inferred from the surrounding context.
 
 Example:
 
@@ -542,8 +542,7 @@ Check instantiation of abstract classes [abstract]
 
 Mypy generates an error if you try to instantiate an abstract base
 class (ABC). An abtract base class is a class with at least one
-abstract method or attribute. (See also :doc:`Python
-abc module documentation <python:library/abc>`)
+abstract method or attribute. (See also :py:mod:`abc` module documentation)
 
 Sometimes a class is made accidentally abstract, often due to an
 unimplemented abstract method. In a case like this you need to provide
@@ -569,10 +568,10 @@ Example:
     # Error: Cannot instantiate abstract class 'Thing' with abstract attribute 'save'  [abstract]
     t = Thing()
 
-Check the target of NewType [valid-newtype]
--------------------------------------------
+Check the target of ``NewType`` [valid-newtype]
+-----------------------------------------------
 
-The target of a ``NewType`` definition must be a class type. It can't
+The target of a :py:func:`NewType <typing.NewType>` definition must be a class type. It can't
 be a union type, ``Any``, or various other special types.
 
 You can also get this error if the target has been imported from a
@@ -593,13 +592,13 @@ 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.
 
-Check the return type of __exit__ [exit-return]
------------------------------------------------
+Check the return type of ``__exit__`` [exit-return]
+---------------------------------------------------
 
-If mypy can determine that ``__exit__`` always returns ``False``, mypy
+If mypy can determine that :py:meth:`__exit__ <object.__exit__>` always returns ``False``, mypy
 checks that the return type is *not* ``bool``.  The boolean value of
 the return type affects which lines mypy thinks are reachable after a
-``with`` statement, since any ``__exit__`` method that can return
+``with`` statement, since any :py:meth:`__exit__ <object.__exit__>` method that can return
 ``True`` may swallow exceptions. An imprecise return type can result
 in mysterious errors reported near ``with`` statements.
 

docs/source/error_code_list2.rst

@@ -135,8 +135,8 @@ Example:
         ...
 
 
-Check that function does not return Any value [no-any-return]
--------------------------------------------------------------
+Check that function does not return ``Any`` value [no-any-return]
+-----------------------------------------------------------------
 
 If you use ``--warn-return-any``, mypy generates an error if you return a
 value with an ``Any`` type in a function that is annotated to return a
@@ -155,8 +155,8 @@ Example:
         # Error: Returning Any from function declared to return "str"  [no-any-return]
         return fields(x)[0]
 
-Check that types have no Any components due to missing imports [no-any-unimported]
-----------------------------------------------------------------------------------
+Check that types have no ``Any`` components due to missing imports [no-any-unimported]
+--------------------------------------------------------------------------------------
 
 If you use ``--disallow-any-unimported``, mypy generates an error if a component of
 a type becomes ``Any`` because mypy couldn't resolve an import. These "stealth"

docs/source/extending_mypy.rst

@@ -14,8 +14,8 @@ what normally would have been the command line arguments to mypy.
 
 Function ``run`` returns a ``Tuple[str, str, int]``, namely
 ``(<normal_report>, <error_report>, <exit_status>)``, in which ``<normal_report>``
-is what mypy normally writes to ``sys.stdout``, ``<error_report>`` is what mypy
-normally writes to ``sys.stderr`` and ``exit_status`` is the exit status mypy normally
+is what mypy normally writes to :py:data:`sys.stdout`, ``<error_report>`` is what mypy
+normally writes to :py:data:`sys.stderr` and ``exit_status`` is the exit status mypy normally
 returns to the operating system.
 
 A trivial example of using the api is the following
@@ -98,7 +98,7 @@ High-level overview
 *******************
 
 Every entry point function should accept a single string argument
-that is a full mypy version and return a subclass of ``mypy.plugins.Plugin``:
+that is a full mypy version and return a subclass of ``mypy.plugin.Plugin``:
 
 .. code-block:: python
 
@@ -174,7 +174,7 @@ For example:
 instead of module level functions.
 
 **get_method_signature_hook()** is used to adjust the signature of a method.
-This includes special Python methods except ``__init__()`` and ``__new__()``.
+This includes special Python methods except :py:meth:`~object.__init__` and :py:meth:`~object.__new__`.
 For example in this code:
 
 .. code-block:: python
@@ -185,12 +185,12 @@ For example in this code:
    x[0] = 42
 
 mypy will call ``get_method_signature_hook("ctypes.Array.__setitem__")``
-so that the plugin can mimic the ``ctypes`` auto-convert behavior.
+so that the plugin can mimic the :py:mod:`ctypes` auto-convert behavior.
 
-**get_attribute_hook** overrides instance member field lookups and property
+**get_attribute_hook()** overrides instance member field lookups and property
 access (not assignments, and not method calls). This hook is only called for
-fields which already exist on the class. *Exception:* if ``__getattr__`` or
-``__getattribute__`` is a method on the class, the hook is called for all
+fields which already exist on the class. *Exception:* if :py:meth:`__getattr__ <object.__getattr__>` or
+:py:meth:`__getattribute__ <object.__getattribute__>` is a method on the class, the hook is called for all
 fields which do not refer to methods.
 
 **get_class_decorator_hook()** can be used to update class definition for

docs/source/faq.rst

@@ -110,17 +110,16 @@ Structural subtyping can be thought of as "static duck typing".
 Some argue that structural subtyping is better suited for languages with duck
 typing such as Python. Mypy however primarily uses nominal subtyping,
 leaving structural subtyping mostly opt-in (except for built-in protocols
-such as ``Iterable`` that always support structural subtyping). Here are some
+such as :py:class:`~typing.Iterable` that always support structural subtyping). Here are some
 reasons why:
 
 1. It is easy to generate short and informative error messages when
    using a nominal type system. This is especially important when
    using type inference.
 
-2. Python provides built-in support for nominal ``isinstance()`` tests and
+2. Python provides built-in support for nominal :py:func:`isinstance` tests and
    they are widely used in programs. Only limited support for structural
-   ``isinstance()`` is available, and it's less type safe than
-   nominal type tests.
+   :py:func:`isinstance` is available, and it's less type safe than nominal type tests.
 
 3. Many programmers are already familiar with static, nominal subtyping and it
    has been successfully used in languages such as Java, C++ and
@@ -164,7 +163,7 @@ monkey patching of methods.
 How is mypy different from Cython?
 **********************************
 
-`Cython :doc:<cython:index>` is a variant of Python that supports
+:doc:`Cython <cython:index>` is a variant of Python that supports
 compilation to CPython C modules. It can give major speedups to
 certain classes of programs compared to CPython, and it provides
 static typing (though this is different from mypy). Mypy differs in

docs/source/final_attrs.rst

@@ -54,7 +54,7 @@ from being overridden in a subclass:
    class ListView(Window):
        BORDER_WIDTH = 3  # Error: can't override a final attribute
 
-You can use ``@property`` to make an attribute read-only, but unlike ``Final``,
+You can use :py:class:`@property <property>` to make an attribute read-only, but unlike ``Final``,
 it doesn't work with module attributes, and it doesn't prevent overriding in
 subclasses.
 
@@ -83,11 +83,11 @@ You can use ``Final`` in one of these forms:
 
 * Finally, you can write ``self.id: Final = 1`` (also optionally with
   a type in square brackets). This is allowed *only* in
-  ``__init__`` methods, so that the final instance attribute is
+  :py:meth:`__init__ <object.__init__>` methods, so that the final instance attribute is
   assigned only once when an instance is created.
 
-Details of using Final
-**********************
+Details of using ``Final``
+**************************
 
 These are the two main rules for defining a final name:
 
@@ -98,7 +98,7 @@ These are the two main rules for defining a final name:
 * There must be *exactly one* assignment to a final name.
 
 A final attribute declared in a class body without an initializer must
-be initialized in the ``__init__`` method (you can skip the
+be initialized in the :py:meth:`__init__ <object.__init__>` method (you can skip the
 initializer in stub files):
 
 .. code-block:: python
@@ -121,9 +121,9 @@ annotations. Using it in any other position is an error. In particular,
    def fun(x: Final[List[int]]) ->  None:  # Error!
        ...
 
-``Final`` and ``ClassVar`` should not be used together. Mypy will infer
+``Final`` and :py:data:`~typing.ClassVar` should not be used together. Mypy will infer
 the scope of a final declaration automatically depending on whether it was
-initialized in the class body or in ``__init__``.
+initialized in the class body or in :py:meth:`__init__ <object.__init__>`.
 
 A final attribute can't be overridden by a subclass (even with another
 explicit final declaration). Note however that a final attribute can