Crossreferences to standard library in mypy docs, part 2 (#7660)

Signed-off-by: Oleg Höfling <oleg.hoefling@gmail.com>

Author: hoefling

docs/source/builtin_types.rst

@@ -23,7 +23,7 @@ Type                   Description
 ====================== ===============================
 
 The type ``Any`` and type constructors such as ``List``, ``Dict``,
-``Iterable`` and ``Sequence`` are defined in the ``typing`` module.
+``Iterable`` and ``Sequence`` are defined in the :py:mod:`typing` module.
 
 The type ``Dict`` is a *generic* class, signified by type arguments within
 ``[...]``. For example, ``Dict[int, str]`` is a dictionary from integers to
@@ -35,6 +35,6 @@ strings and ``Dict[Any, Any]`` is a dictionary of dynamically typed
 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/common_issues.rst

@@ -69,7 +69,7 @@ flagged as an error.
   :ref:`reveal_type() <reveal-type>` might come in handy.
 
   Note that sometimes library stubs have imprecise type information,
-  e.g. the ``pow()`` builtin returns ``Any`` (see `typeshed issue 285
+  e.g. the :py:func:`pow` builtin returns ``Any`` (see `typeshed issue 285
   <https://github.com/python/typeshed/issues/285>`_ for the reason).
 
 - **Some imports may be silently ignored**.  Another source of
@@ -143,7 +143,7 @@ Another option is to explicitly annotate values with type ``Any`` --
 mypy will let you perform arbitrary operations on ``Any``
 values. Sometimes there is no more precise type you can use for a
 particular value, especially if you use dynamic Python features
-such as ``__getattr__``:
+such as :py:meth:`__getattr__ <object.__getattr__>`:
 
 .. code-block:: python
 
@@ -326,7 +326,7 @@ above example:
 Complex type tests
 ------------------
 
-Mypy can usually infer the types correctly when using ``isinstance()``
+Mypy can usually infer the types correctly when using :py:func:`isinstance <isinstance>`
 type tests, but for other kinds of checks you may need to add an
 explicit type cast:
 
@@ -342,17 +342,17 @@ explicit type cast:
 
 .. note::
 
-    Note that the ``object`` type used in the above example is similar
+    Note that the :py:class:`object` type used in the above example is similar
     to ``Object`` in Java: it only supports operations defined for *all*
-    objects, such as equality and ``isinstance()``. The type ``Any``,
+    objects, such as equality and :py:func:`isinstance`. The type ``Any``,
     in contrast, supports all operations, even if they may fail at
     runtime. The cast above would have been unnecessary if the type of
     ``o`` was ``Any``.
 
-Mypy can't infer the type of ``o`` after the ``type()`` check
-because it only knows about ``isinstance()`` (and the latter is better
+Mypy can't infer the type of ``o`` after the :py:class:`type() <type>` check
+because it only knows about :py:func:`isinstance` (and the latter is better
 style anyway).  We can write the above code without a cast by using
-``isinstance()``:
+:py:func:`isinstance`:
 
 .. code-block:: python
 
@@ -379,8 +379,8 @@ the targeted Python version or platform. This allows you to more effectively
 typecheck code that supports multiple versions of Python or multiple operating
 systems.
 
-More specifically, mypy will understand the use of ``sys.version_info`` and
-``sys.platform`` checks within ``if/elif/else`` statements. For example:
+More specifically, mypy will understand the use of :py:data:`sys.version_info` and
+:py:data:`sys.platform` checks within ``if/elif/else`` statements. For example:
 
 .. code-block:: python
 
@@ -417,14 +417,14 @@ Example:
    # The rest of this file doesn't apply to Windows.
 
 Some other expressions exhibit similar behavior; in particular,
-``typing.TYPE_CHECKING``, variables named ``MYPY``, and any variable
+:py:data:`~typing.TYPE_CHECKING`, variables named ``MYPY``, and any variable
 whose name is passed to ``--always-true`` or ``--always-false``.
 (However, ``True`` and ``False`` are not treated specially!)
 
 .. note::
 
    Mypy currently does not support more complex checks, and does not assign
-   any special meaning when assigning a ``sys.version_info`` or ``sys.platform``
+   any special meaning when assigning a :py:data:`sys.version_info` or :py:data:`sys.platform`
    check to a variable. This may change in future versions of mypy.
 
 By default, mypy will use your current version of Python and your current
@@ -514,10 +514,10 @@ File ``bar.py``:
 
 .. note::
 
-   The ``TYPE_CHECKING`` constant defined by the ``typing`` module
+   The :py:data:`~typing.TYPE_CHECKING` constant defined by the :py:mod:`typing` module
    is ``False`` at runtime but ``True`` while type checking.
 
-Python 3.5.1 doesn't have ``typing.TYPE_CHECKING``. An alternative is
+Python 3.5.1 doesn't have :py:data:`~typing.TYPE_CHECKING`. An alternative is
 to define a constant named ``MYPY`` that has the value ``False``
 at runtime. Mypy considers it to be ``True`` when type checking.
 Here's the above example modified to use ``MYPY``:
@@ -538,7 +538,7 @@ Using classes that are generic in stubs but not at runtime
 ----------------------------------------------------------
 
 Some classes are declared as generic in stubs, but not at runtime. Examples
-in the standard library include ``os.PathLike`` and ``queue.Queue``.
+in the standard library include :py:class:`os.PathLike` and :py:class:`queue.Queue`.
 Subscripting such a class will result in a runtime error:
 
 .. code-block:: python
@@ -551,7 +551,7 @@ Subscripting such a class will result in a runtime error:
    results: Queue[int] = Queue()  # TypeError: 'type' object is not subscriptable
 
 To avoid these errors while still having precise types you can either use
-string literal types or ``typing.TYPE_CHECKING``:
+string literal types or :py:data:`~typing.TYPE_CHECKING`:
 
 .. code-block:: python
 
@@ -615,7 +615,7 @@ Consider this example:
    c.x << 5  # Since this will fail!
 
 To work around this problem consider whether "mutating" is actually part
-of a protocol. If not, then one can use a ``@property`` in
+of a protocol. If not, then one can use a :py:class:`@property <property>` in
 the protocol definition:
 
 .. code-block:: python

docs/source/config_file.rst

@@ -254,8 +254,8 @@ For more information, see the :ref:`None and optional handling <none-and-optiona
 section of the command line docs.
 
 ``no_implicit_optional`` (bool, default False)
-    Changes the treatment of arguments with a default value of None by not implicitly
-    making their type Optional.
+    Changes the treatment of arguments with a default value of ``None`` by not implicitly
+    making their type :py:data:`~typing.Optional`.
 
 ``strict_optional`` (bool, default True)
     Enables or disables strict Optional checks. If False, mypy treats ``None``
@@ -377,8 +377,9 @@ a list of import discovery options that may be used
     User home directory and environment variables will be expanded.
 
 ``files`` (string)
+
     A comma-separated list of paths which should be checked by mypy if none are given on the command
-    line. Supports recursive file globbing using :doc:`library/glob`, where ``*`` (e.g. ``*.py``) matches
+    line. Supports recursive file globbing using :py:mod:`glob`, where ``*`` (e.g. ``*.py``) matches
     files in the current directory and ``**/`` (e.g. ``**/*.py``) matches files in any directories below
     the current one. User home directory and environment variables will be expanded.
 
@@ -399,7 +400,7 @@ section of the command line docs.
     Specifies the OS platform for the target program, for example
     ``darwin`` or ``win32`` (meaning OS X or Windows, respectively).
     The default is the current platform as revealed by Python's
-    ``sys.platform`` variable.
+    :py:data:`sys.platform` variable.
 
 
 Incremental mode
@@ -418,7 +419,7 @@ section of the command line docs.
     variable.
 
     Note that the cache is only read when incremental mode is enabled
-    but is always written to, unless the value is set to ``/dev/nul``
+    but is always written to, unless the value is set to ``/dev/null``
     (UNIX) or ``nul`` (Windows).
 
 ``skip_version_check`` (bool, default False)
@@ -462,7 +463,7 @@ section of the command line docs.
     Shows traceback on fatal error.
 
 ``custom_typing_module`` (string)
-    Specifies a custom module to use as a substitute for the ``typing`` module.
+    Specifies a custom module to use as a substitute for the :py:mod:`typing` module.
 
 ``custom_typeshed_dir`` (string)
     Specifies an alternative directory to look for stubs instead of the

docs/source/dynamic_typing.rst

@@ -54,10 +54,10 @@ less effective, unless you are careful.
 Any vs. object
 --------------
 
-The type ``object`` is another type that can have an instance of arbitrary
-type as a value. Unlike ``Any``, ``object`` is an ordinary static type (it
+The type :py:class:`object` is another type that can have an instance of arbitrary
+type as a value. Unlike ``Any``, :py:class:`object` is an ordinary static type (it
 is similar to ``Object`` in Java), and only operations valid for *all*
-types are accepted for ``object`` values. These are all valid:
+types are accepted for :py:class:`object` values. These are all valid:
 
 .. code-block:: python
 
@@ -80,7 +80,7 @@ operations:
         n = 1  # type: int
         n = o         # Error!
 
-You can use ``cast()`` (see chapter :ref:`casts`) or ``isinstance`` to
-go from a general type such as ``object`` to a more specific
-type (subtype) such as ``int``.  ``cast()`` is not needed with
+You can use :py:func:`~typing.cast` (see chapter :ref:`casts`) or :py:func:`isinstance` to
+go from a general type such as :py:class:`object` to a more specific
+type (subtype) such as ``int``.  :py:func:`~typing.cast` is not needed with
 dynamically typed values (values with type ``Any``).