revisited builtin_types.rst, common_issues.rst, config_file.rst

Signed-off-by: Oleg Höfling <oleg.hoefling@gmail.com>
python · gvanrossum · Oct 9, 2019 · Oct 8, 2019 · Oct 8, 2019 · Oct 8, 2019
commit e4333f557353ce7c225426f13f8d6b60d4d8499c
diff --git a/docs/source/builtin_types.rst b/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.
diff --git a/docs/source/common_issues.rst b/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

diff --git a/docs/source/config_file.rst b/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
 For more information see :doc:`official docs <python:library/dataclasses>` 
 Mypy supports Python :doc:`abstract base classes <library/abc>` (ABCs). Abstract classes 
 :doc:`ini file <python:library/configparser>` format. It should contain 
 abstract method or attribute. (See also :doc:`Python 
 abc module documentation <python:library/abc>`) 
 For more information see :doc:`official docs <python:library/dataclasses>` 
 Mypy supports Python :doc:`abstract base classes <library/abc>` (ABCs). Abstract classes 
 :doc:`ini file <python:library/configparser>` format. It should contain 
 abstract method or attribute. (See also :doc:`Python 
 abc module documentation <python:library/abc>`) 
     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
@@ -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