added crossrefs to standard library

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

Author: hoefling

docs/source/additional_features.rst

@@ -26,8 +26,8 @@ They can be defined using the :py:func:`@dataclasses.dataclass
     test = Application("Testing...")  # OK
     bad = Application("Testing...", "with plugin")  # Error: List[str] expected
 
-Mypy will detect special methods (such as ``__lt__``) depending on the flags used to
-define dataclasses. For example:
+Mypy will detect special methods (such as :py:meth:`__lt__ <object.__lt__>`)
+depending on the flags used to define dataclasses. For example:
 
 .. code-block:: python
 
@@ -72,10 +72,11 @@ and :pep:`557`.
 Caveats/Known Issues
 ====================
 
-Some functions in the ``dataclasses`` module, such as ``replace()`` and ``asdict()``,
+Some functions in the :py:mod:`dataclasses` module, such as
+:py:func:`~dataclasses.replace` and :py:func:`~dataclasses.asdict`,
 have imprecise (too permissive) types. This will be fixed in future releases.
 
-Mypy does not yet recognize aliases of ``dataclasses.dataclass``, and will
+Mypy does not yet recognize aliases of :py:func:`dataclasses.dataclass`, and will
 probably never recognize dynamically computed decorators. The following examples
 do **not** work:
 
@@ -140,9 +141,9 @@ If you're using ``auto_attribs=True`` you must use variable annotations.
         three: int = attr.ib(8)
 
 Typeshed has a couple of "white lie" annotations to make type checking
-easier. ``attr.ib`` and ``attr.Factory`` actually return objects, but the
-annotation says these return the types that they expect to be assigned to.
-That enables this to work:
+easier. :py:func:`attr.ib` and :py:class:`attr.Factory` actually
+return objects, but the annotation says these return the types that
+they expect to be assigned to. That enables this to work:
 
 .. code-block:: python
 
@@ -175,7 +176,7 @@ Caveats/Known Issues
 
 * Currently, ``converter`` only supports named functions.  If mypy finds something else it
   will complain about not understanding the argument and the type annotation in
-  ``__init__`` will be replaced by ``Any``.
+  ``__init__`` will be replaced by :py:data:`~typing.Any`.
 
 * :ref:`Validator decorators <attrs:examples_validators>`
   and `default decorators <http://www.attrs.org/en/stable/examples.html#defaults>`_
@@ -249,7 +250,7 @@ Your CI script might work like this:
 * Create a tarball from the ``.mypy_cache`` directory.
 
 * Determine the current git master branch commit id (say, using
-  ``git rev-parse HEAD``).
+  :code:`git rev-parse HEAD`).
 
 * Upload the tarball to the shared repository with a name derived from the
   commit id.
@@ -348,16 +349,17 @@ Extended Callable types
    This feature is deprecated.  You can use
    :ref:`callback protocols <callback_protocols>` as a replacement.
 
-As an experimental mypy extension, you can specify ``Callable`` types
-that support keyword arguments, optional arguments, and more.  When
-you specify the arguments of a Callable, you can choose to supply just
+As an experimental mypy extension, you can specify
+:py:data:`~typing.Callable` types that support keyword arguments,
+optional arguments, and more. When you specify the arguments of a
+:py:data:`~typing.Callable`, you can choose to supply just
 the type of a nameless positional argument, or an "argument specifier"
 representing a more complicated form of argument.  This allows one to
 more closely emulate the full range of possibilities given by the
 ``def`` statement in Python.
 
 As an example, here's a complicated function definition and the
-corresponding ``Callable``:
+corresponding :py:data:`~typing.Callable`:
 
 .. code-block:: python
 
@@ -431,10 +433,10 @@ purpose:
        # A single KwArg() specifier represents all remaining
        # keyword arguments.
 
-In all cases, the ``type`` argument defaults to ``Any``, and if the
-``name`` argument is omitted the argument has no name (the name is
-required for ``NamedArg`` and ``DefaultNamedArg``).  A basic
-``Callable`` such as
+In all cases, the ``type`` argument defaults to :py:data:`~typing.Any`,
+and if the ``name`` argument is omitted the argument has no name
+(the name is required for ``NamedArg`` and ``DefaultNamedArg``).
+A basic :py:data:`~typing.Callable` such as
 
 .. code-block:: python
 
@@ -446,7 +448,7 @@ is equivalent to the following:
 
    MyFunc = Callable[[Arg(int), Arg(str), Arg(int)], float]
 
-A ``Callable`` with unspecified argument types, such as
+A :py:data:`~typing.Callable` with unspecified argument types, such as
 
 .. code-block:: python
 

docs/source/builtin_types.rst

@@ -22,19 +22,22 @@ Type                   Description
 ``Any``                dynamically typed value with an arbitrary type
 ====================== ===============================
 
-The type ``Any`` and type constructors such as ``List``, ``Dict``,
-``Iterable`` and ``Sequence`` are defined in the ``typing`` module.
+The type :py:data:`~typing.Any` and type constructors such as :py:class:`~typing.List`,
+:py:class:`~typing.Dict`, :py:class:`~typing.Iterable` and :py:class:`~typing.Sequence`
+are defined in the :py:mod:`typing` module.
 
-The type ``Dict`` is a *generic* class, signified by type arguments within
+The type :py:class:`~typing.Dict` is a *generic* class, signified by type arguments within
 ``[...]``. For example, ``Dict[int, str]`` is a dictionary from integers to
 strings and ``Dict[Any, Any]`` is a dictionary of dynamically typed
-(arbitrary) values and keys. ``List`` is another generic class. ``Dict`` and
-``List`` are aliases for the built-ins ``dict`` and ``list``, respectively.
+(arbitrary) values and keys. :py:class:`~typing.List` is another generic class.
+:py:class:`~typing.Dict` and :py:class:`~typing.List` are aliases for the
+built-ins :py:class:`dict` and :py:class:`list`, respectively.
 
-``Iterable``, ``Sequence``, and ``Mapping`` are generic types that
+:py:class:`~typing.Iterable`, :py:class:`~typing.Sequence`, and
+:py:class:`~typing.Mapping` are generic types that
 correspond to Python protocols. For example, a ``str`` object or a
 ``List[str]`` object is valid
 when ``Iterable[str]`` or ``Sequence[str]`` is expected. Note that even though
-they are similar to abstract base classes defined in ``collections.abc``
+they are similar to abstract base classes defined in :py:mod:`collections.abc`
 (formerly ``collections``), they are not identical, since the built-in
 collection type objects do not support indexing.

docs/source/casts.rst

@@ -6,8 +6,8 @@ Casts and type assertions
 Mypy supports type casts that are usually used to coerce a statically
 typed value to a subtype. Unlike languages such as Java or C#,
 however, mypy casts are only used as hints for the type checker, and they
-don't perform a runtime type check. Use the function ``cast`` to perform a
-cast:
+don't perform a runtime type check. Use the function :py:func:`~typing.cast`
+to perform a cast:
 
 .. code-block:: python
 
@@ -34,10 +34,11 @@ quite understand what is going on.
           assert isinstance(o, int)
           print(o + 5)  # OK: type of 'o' is 'int' here
 
-You don't need a cast for expressions with type ``Any``, or when
-assigning to a variable with type ``Any``, as was explained earlier.
-You can also use ``Any`` as the cast target type -- this lets you perform
-any operations on the result. For example:
+You don't need a cast for expressions with type :py:data:`~typing.Any`,
+or when assigning to a variable with type :py:data:`~typing.Any`,
+as was explained earlier.
+You can also use :py:data:`~typing.Any` as the cast target type --
+this lets you perform any operations on the result. For example:
 
 .. code-block:: python
 

docs/source/class_basics.rst

@@ -1,9 +1,10 @@
 Class basics
 ============
 
+
 This section will help get you started annotating your
-classes. Built-in classes such as ``int`` also follow these same
-rules.
+classes. Built-in classes such as :py:class:`int` also
+follow these same rules.
 
 Instance and class attributes
 *****************************
@@ -24,8 +25,8 @@ initialized within the class. Mypy infers the types of attributes:
    a.y = 3  # Error: 'A' has no attribute 'y'
 
 This is a bit like each class having an implicitly defined
-``__slots__`` attribute. This is only enforced during type
-checking and not when your program is running.
+:py:data:`__slots__ <object.__slots__>` attribute. This is only
+enforced during type checking and not when your program is running.
 
 You can declare types of variables in the class body explicitly using
 a type annotation:
@@ -40,7 +41,7 @@ a type annotation:
 
 As in Python generally, a variable defined in the class body can be used
 as a class or an instance variable. (As discussed in the next section, you
-can override this with a ``ClassVar`` annotation.)
+can override this with a :py:data:`~typing.ClassVar` annotation.)
 
 Type comments work as well, if you need to support Python versions earlier
 than 3.6:
@@ -51,9 +52,9 @@ than 3.6:
        x = None  # type: List[int]  # Declare attribute 'x' of type List[int]
 
 Note that attribute definitions in the class body that use a type comment
-are special: a ``None`` value is valid as the initializer, even though
+are special: a :py:data:`None` value is valid as the initializer, even though
 the declared type is not optional. This should be used sparingly, as this can
-result in ``None``-related runtime errors that mypy can't detect.
+result in :py:data:`None`-related runtime errors that mypy can't detect.
 
 Similarly, you can give explicit types to instance variables defined
 in a method:
@@ -78,15 +79,16 @@ to it explicitly using ``self``:
            a = self
            a.x = 1      # Error: 'x' not defined
 
-Annotating `__init__` methods
-*****************************
+Annotating ``__init__`` methods
+*******************************
 
-The ``__init__`` method is somewhat special -- it doesn't return a
-value.  This is best expressed as ``-> None``.  However, since many feel
-this is redundant, it is allowed to omit the return type declaration
-on ``__init__`` methods **if at least one argument is annotated**.  For
-example, in the following classes ``__init__`` is considered fully
-annotated:
+The :py:meth:`__init__ <object.__init__>` method is somewhat special --
+it doesn't return a value.  This is best expressed as ``-> None``.
+However, since many feel this is redundant, it is allowed to omit
+the return type declaration on :py:meth:`__init__ <object.__init__>`
+methods **if at least one argument is annotated**.  For example,
+in the following classes :py:meth:`__init__ <object.__init__>`
+is considered fully annotated:
 
 .. code-block:: python
 
@@ -98,8 +100,8 @@ annotated:
        def __init__(self, arg: int):
            self.var = arg
 
-However, if ``__init__`` has no annotated arguments and no return type
-annotation, it is considered an untyped method:
+However, if :py:meth:`__init__ <object.__init__>` has no annotated
+arguments and no return type annotation, it is considered an untyped method:
 
 .. code-block:: python
 
@@ -130,12 +132,14 @@ particular attribute should not be set on instances:
 .. note::
 
    If you need to support Python 3 versions 3.5.2 or earlier, you have
-   to import ``ClassVar`` from ``typing_extensions`` instead (available on
-   PyPI). If you use Python 2.7, you can import it from ``typing``.
+   to import :py:data:`~typing.ClassVar` from ``typing_extensions``
+   instead (available on PyPI). If you use Python 2.7, you can import it
+   from :py:mod:`typing`.
 
 It's not necessary to annotate all class variables using
-``ClassVar``. An attribute without the ``ClassVar`` annotation can
-still be used as a class variable. However, mypy won't prevent it from
+:py:data:`~typing.ClassVar`. An attribute without the
+:py:data:`~typing.ClassVar` annotation can still be used
+as a class variable. However, mypy won't prevent it from
 being used as an instance variable, as discussed previously:
 
 .. code-block:: python
@@ -148,27 +152,29 @@ being used as an instance variable, as discussed previously:
   a = A()
   a.x = 1  # Also OK
 
-Note that ``ClassVar`` is not a class, and you can't use it with
-``isinstance()`` or ``issubclass()``. It does not change Python
-runtime behavior -- it's only for type checkers such as mypy (and
-also helpful for human readers).
+Note that :py:data:`~typing.ClassVar` is not a class, and
+you can't use it with :py:func:`isinstance` or :py:func:`issubclass`.
+It does not change Python runtime behavior -- it's only for
+type checkers such as mypy (and also helpful for human readers).
 
 You can also omit the square brackets and the variable type in
-a ``ClassVar`` annotation, but this might not do what you'd expect:
+a :py:data:`~typing.ClassVar` annotation, but this might not do
+what you'd expect:
 
 .. code-block:: python
 
    class A:
        y: ClassVar = 0  # Type implicitly Any!
 
-In this case the type of the attribute will be implicitly ``Any``.
+In this case the type of the attribute will be implicitly
+:py:data:`~typing.Any`.
 This behavior will change in the future, since it's surprising.
 
 .. note::
-   A ``ClassVar`` type parameter cannot include type variables:
-   ``ClassVar[T]`` and ``ClassVar[List[T]]``
-   are both invalid if ``T`` is a type variable (see :ref:`generic-classes`
-   for more about type variables).
+   A :py:data:`~typing.ClassVar` type parameter cannot include
+   type variables: ``ClassVar[T]`` and ``ClassVar[List[T]]``
+   are both invalid if ``T`` is a type variable (see
+   :ref:`generic-classes` for more about type variables).
 
 Overriding statically typed methods
 ***********************************
@@ -235,8 +241,9 @@ Abstract base classes and multiple inheritance
 Mypy supports Python abstract base classes (ABCs). Abstract classes
 have at least one abstract method or property that must be implemented
 by any *concrete* (non-abstract) subclass. You can define abstract base
-classes using the ``abc.ABCMeta`` metaclass and the ``abc.abstractmethod``
-function decorator. Example:
+classes using the :py:class:`abc.ABCMeta` metaclass and the
+:py:func:`@abc.abstractmethod <abc.abstractmethod>` function decorator.
+Example:
 
 .. code-block:: python
 
@@ -263,12 +270,12 @@ function decorator. Example:
 
 .. note::
 
-   In Python 2.7 you have to use ``@abc.abstractproperty`` to define
-   an abstract property.
+   In Python 2.7 you have to use :py:func:`@abc.abstractproperty
+   <abc.abstractproperty>` to define an abstract property.
 
 Note that mypy performs checking for unimplemented abstract methods
-even if you omit the ``ABCMeta`` metaclass. This can be useful if the
-metaclass would cause runtime metaclass conflicts.
+even if you omit the :py:class:`~abc.ABCMeta` metaclass. This can be
+useful if the metaclass would cause runtime metaclass conflicts.
 
 Since you can't create instances of ABCs, they are most commonly used in
 type annotations. For example, this method accepts arbitrary iterables