Replace hardcoded links with intersphinx refs in docs (#7623)

Configured intersphinx extension, replaced external links with intersphinx refs and pep role.

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

Author: hoefling

docs/source/additional_features.rst

@@ -9,9 +9,10 @@ of the previous sections.
 Dataclasses
 ***********
 
-In Python 3.7, a new ``dataclasses`` module has been added to the standard library.
+In Python 3.7, a new :py:mod:`dataclasses` module has been added to the standard library.
 This module allows defining and customizing simple boilerplate-free classes.
-They can be defined using the ``@dataclasses.dataclass`` decorator:
+They can be defined using the :py:func:`@dataclasses.dataclass
+<python:dataclasses.dataclass>` decorator:
 
 .. code-block:: python
 
@@ -65,8 +66,8 @@ class can be used:
 
     val = unbox(BoxedData(42, "<important>"))  # OK, inferred type is int
 
-For more information see `official docs <https://docs.python.org/3/library/dataclasses.html>`_
-and `PEP 557 <https://www.python.org/dev/peps/pep-0557/>`_.
+For more information see :doc:`official docs <python:library/dataclasses>`
+and :pep:`557`.
 
 Caveats/Known Issues
 ====================
@@ -110,7 +111,7 @@ do **not** work:
 The attrs package
 *****************
 
-`attrs <http://www.attrs.org/en/stable>`_ is a package that lets you define
+:doc:`attrs <attrs:index>` is a package that lets you define
 classes without writing boilerplate code. Mypy can detect uses of the
 package and will generate the necessary method definitions for decorated
 classes using the type annotations it finds.
@@ -176,7 +177,7 @@ Caveats/Known Issues
   will complain about not understanding the argument and the type annotation in
   ``__init__`` will be replaced by ``Any``.
 
-* `Validator decorators <http://www.attrs.org/en/stable/examples.html#validators>`_
+* :ref:`Validator decorators <attrs:examples_validators>`
   and `default decorators <http://www.attrs.org/en/stable/examples.html#defaults>`_
   are not type-checked against the attribute they are setting/validating.
 

docs/source/cheat_sheet.rst

@@ -3,8 +3,7 @@
 Type hints cheat sheet (Python 2)
 =================================
 
-This document is a quick cheat sheet showing how the
-`PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ type
+This document is a quick cheat sheet showing how the :pep:`484` type
 language represents various common types in Python 2.
 
 .. note::

docs/source/cheat_sheet_py3.rst

@@ -3,8 +3,7 @@
 Type hints cheat sheet (Python 3)
 =================================
 
-This document is a quick cheat sheet showing how the
-`PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ type
+This document is a quick cheat sheet showing how the :pep:`484` type
 annotation notation represents various common types in Python 3.
 
 .. note::
@@ -18,9 +17,8 @@ annotation notation represents various common types in Python 3.
 Variables
 *********
 
-Python 3.6 introduced a syntax for annotating variables in
-`PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ and
-we use it in most examples.
+Python 3.6 introduced a syntax for annotating variables in :pep:`526`
+and we use it in most examples.
 
 .. code-block:: python
 

docs/source/command_line.rst

@@ -78,7 +78,7 @@ imports.
 
 ``--namespace-packages``
     This flag enables import discovery to use namespace packages (see
-    `PEP 420`_).  In particular, this allows discovery of imported
+    :pep:`420`).  In particular, this allows discovery of imported
     packages that don't have an ``__init__.py`` (or ``__init__.pyi``)
     file.
 
@@ -127,23 +127,23 @@ imports.
     see :ref:`Following imports <follow-imports>`.
 
 ``--python-executable EXECUTABLE``
-    This flag will have mypy collect type information from `PEP 561`_
+    This flag will have mypy collect type information from :pep:`561`
     compliant packages installed for the Python executable ``EXECUTABLE``.
-    If not provided, mypy will use PEP 561 compliant packages installed for
+    If not provided, mypy will use :pep:`561` compliant packages installed for
     the Python executable running mypy.
 
-    See :ref:`installed-packages` for more on making PEP 561 compliant packages.
+    See :ref:`installed-packages` for more on making :pep:`561` compliant packages.
 
 ``--no-site-packages``
-    This flag will disable searching for `PEP 561`_ compliant packages. This
+    This flag will disable searching for :pep:`561` compliant packages. This
     will also disable searching for a usable Python executable.
 
     Use this  flag if mypy cannot find a Python executable for the version of
-    Python being checked, and you don't need to use PEP 561 typed packages.
+    Python being checked, and you don't need to use :pep:`561` typed packages.
     Otherwise, use ``--python-executable``.
 
 ``--no-silence-site-packages``
-    By default, mypy will suppress any error messages generated within PEP 561
+    By default, mypy will suppress any error messages generated within :pep:`561`
     compliant packages. Adding this flag will disable this behavior.
 
 
@@ -165,7 +165,7 @@ For more information on how to use these flags, see :ref:`version_and_platform_c
     ``--py2`` flags are aliases for ``--python-version 2.7``.
 
     This flag will attempt to find a Python executable of the corresponding
-    version to search for `PEP 561`_ compliant packages. If you'd like to
+    version to search for :pep:`561` compliant packages. If you'd like to
     disable this, use the ``--no-site-packages`` flag (see
     :ref:`import-discovery` for more details).
 
@@ -178,7 +178,7 @@ For more information on how to use these flags, see :ref:`version_and_platform_c
     default to using whatever operating system you are currently using.
 
     The ``PLATFORM`` parameter may be any string supported by
-    `sys.platform <https://docs.python.org/3/library/sys.html#sys.platform>`_.
+    :py:data:`sys.platform`.
 
 .. _always-true:
 
@@ -680,8 +680,4 @@ Miscellaneous
     have many scripts that import a large package, the behavior enabled
     by this flag is often more convenient.)
 
-.. _PEP 420: https://www.python.org/dev/peps/pep-0420/
-
-.. _PEP 561: https://www.python.org/dev/peps/pep-0561/
-
 .. _lxml: https://pypi.org/project/lxml/

docs/source/common_issues.rst

@@ -438,8 +438,7 @@ to have Python 2.7 installed to perform this check.
 
 To target a different operating system, use the ``--platform PLATFORM`` flag.
 For example, to verify your code typechecks if it were run in Windows, pass
-in ``--platform win32``. See the documentation for
-`sys.platform <https://docs.python.org/3/library/sys.html#sys.platform>`_
+in ``--platform win32``. See the documentation for :py:data:`sys.platform`
 for examples of valid platform parameters.
 
 .. _reveal-type:

docs/source/conf.py

@@ -30,7 +30,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -266,3 +266,11 @@
 #texinfo_no_detailmenu = False
 
 rst_prolog = '.. |...| unicode:: U+2026   .. ellipsis\n'
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'six': ('https://six.readthedocs.io', None),
+    'attrs': ('http://www.attrs.org/en/stable', None),
+    'cython': ('http://docs.cython.org/en/latest', None),
+    'monkeytype': ('https://monkeytype.readthedocs.io/en/latest', None),
+}

docs/source/config_file.rst

@@ -29,10 +29,9 @@ Config file format
 ******************
 
 The configuration file format is the usual
-`ini file <https://docs.python.org/3.6/library/configparser.html>`_
-format.  It should contain section names in square brackets and flag
-settings of the form `NAME = VALUE`.  Comments start with ``#``
-characters.
+:doc:`ini file <python:library/configparser>` format. It should contain
+section names in square brackets and flag settings of the form
+`NAME = VALUE`. Comments start with ``#`` characters.
 
 - A section named ``[mypy]`` must be present.  This specifies
   the global flags. The ``setup.cfg`` file is an exception to this.
@@ -357,7 +356,7 @@ a list of import discovery options that may be used
 :ref:`both per-module and globally <config-file-import-discovery-per-module>`.
 
 ``namespace_packages`` (bool, default False)
-    Enables PEP 420 style namespace packages.  See :ref:`the
+    Enables :pep:`420` style namespace packages.  See :ref:`the
     corresponding flag <import-discovery>` for more information.
 
 ``python_executable`` (string)
@@ -367,7 +366,7 @@ a list of import discovery options that may be used
     the executable used to run mypy.
 
 ``no_silence_site_packages`` (bool, default False)
-    Enables reporting error messages generated within PEP 561 compliant packages.
+    Enables reporting error messages generated within :pep:`561` compliant packages.
     Those error messages are suppressed by default, since you are usually
     not able to control errors in 3rd party code.
 
@@ -379,9 +378,8 @@ a list of import discovery options that may be used
 
 ``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
-    [the glob library](https://docs.python.org/3/library/glob.html), where `*` (e.g. `*.py`) matches
-    files in the current directory and `**/` (e.g. `**/*.py`) matches files in any directories below
+    line. Supports recursive file globbing using :doc:`library/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.
 
 

docs/source/error_code_list.rst

@@ -542,8 +542,8 @@ 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 `Python
-abc module documentation <https://docs.python.org/3/library/abc.html>`_.)
+abstract method or attribute. (See also :doc:`Python
+abc module documentation <python:library/abc>`)
 
 Sometimes a class is made accidentally abstract, often due to an
 unimplemented abstract method. In a case like this you need to provide

docs/source/existing_code.rst

@@ -20,7 +20,7 @@ These steps will get you started with mypy on an existing codebase:
 
 5. Write annotations as you modify existing code and write new code
 
-6. Use MonkeyType or PyAnnotate to automatically annotate legacy code
+6. Use :doc:`monkeytype:index` or `PyAnnotate`_ to automatically annotate legacy code
 
 We discuss all of these points in some detail below, and a few optional
 follow-up steps.
@@ -145,8 +145,7 @@ Automate annotation of legacy code
 
 There are tools for automatically adding draft annotations
 based on type profiles collected at runtime.  Tools include
-`MonkeyType <https://github.com/Instagram/MonkeyType>`_
-(Python 3) and `PyAnnotate <https://github.com/dropbox/pyannotate>`_
+:doc:`monkeytype:index` (Python 3) and `PyAnnotate`_
 (type comments only).
 
 A simple approach is to collect types from test runs. This may work
@@ -177,3 +176,5 @@ catch more bugs. For example, you can ask mypy to require annotations
 for all functions in certain modules to avoid accidentally introducing
 code that won't be type checked. Refer to :ref:`command-line` for the
 details.
+
+.. _PyAnnotate: https://github.com/dropbox/pyannotate

docs/source/extending_mypy.rst

@@ -43,12 +43,12 @@ Extending mypy using plugins
 Python is a highly dynamic language and has extensive metaprogramming
 capabilities. Many popular libraries use these to create APIs that may
 be more flexible and/or natural for humans, but are hard to express using
-static types. Extending the PEP 484 type system to accommodate all existing
+static types. Extending the :pep:`484` type system to accommodate all existing
 dynamic patterns is impractical and often just impossible.
 
 Mypy supports a plugin system that lets you customize the way mypy type checks
 code. This can be useful if you want to extend mypy so it can type check code
-that uses a library that is difficult to express using just PEP 484 types.
+that uses a library that is difficult to express using just :pep:`484` types.
 
 The plugin system is focused on improving mypy's understanding
 of *semantics* of third party frameworks. There is currently no way to define
@@ -139,7 +139,7 @@ Current list of plugin hooks
 ****************************
 
 **get_type_analyze_hook()** customizes behaviour of the type analyzer.
-For example, PEP 484 doesn't support defining variadic generic types:
+For example, :pep:`484` doesn't support defining variadic generic types:
 
 .. code-block:: python
 

docs/source/faq.rst

@@ -88,8 +88,8 @@ the scope of the mypy project.
 How do I type check my Python 2 code?
 *************************************
 
-You can use a `comment-based function annotation syntax
-<https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code>`_
+You can use a :pep:`comment-based function annotation syntax
+<484#suggested-syntax-for-python-2-7-and-straddling-code>`
 and use the ``--py2`` command-line option to type check your Python 2 code.
 You'll also need to install ``typing`` for Python 2 via ``pip install typing``.
 
@@ -131,8 +131,7 @@ may be more flexible if it is typed with protocols. Also, using protocol types
 removes the necessity to explicitly declare implementations of ABCs.
 As a rule of thumb, we recommend using nominal classes where possible, and
 protocols where necessary. For more details about protocol types and structural
-subtyping see :ref:`protocol-types` and
-`PEP 544 <https://www.python.org/dev/peps/pep-0544/>`_.
+subtyping see :ref:`protocol-types` and :pep:`544`.
 
 I like Python and I have no need for static typing
 **************************************************
@@ -165,7 +164,7 @@ monkey patching of methods.
 How is mypy different from Cython?
 **********************************
 
-`Cython <http://cython.org/>`_ is a variant of Python that supports
+`Cython :doc:<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/generics.rst

@@ -662,8 +662,8 @@ Type aliases can be generic. In this case they can be used in two ways:
 Subscripted aliases are equivalent to original types with substituted type
 variables, so the number of type arguments must match the number of free type variables
 in the generic type alias. Unsubscripted aliases are treated as original types with free
-variables replaced with ``Any``. Examples (following `PEP 484
-<https://www.python.org/dev/peps/pep-0484/#type-aliases>`_):
+variables replaced with ``Any``. Examples (following :pep:`PEP 484: Type aliases
+<484#type-aliases>`):
 
 .. code-block:: python
 

docs/source/getting_started.rst

@@ -88,14 +88,12 @@ calls since the arguments have invalid types:
    greeting(b'Alice')  # Argument 1 to "greeting" has incompatible type "bytes"; expected "str"
 
 Note that this is all still valid Python 3 code! The function annotation syntax
-shown above was added to Python `as a part of Python 3.0 <pep3107_>`_.
+shown above was added to Python :pep:`as a part of Python 3.0 <3107>`.
 
 If you are trying to type check Python 2 code, you can add type hints
 using a comment-based syntax instead of the Python 3 annotation syntax.
 See our section on :ref:`typing Python 2 code <python2>` for more details.
 
-.. _pep3107: https://www.python.org/dev/peps/pep-3107/
-
 Being able to pick whether you want a function to be dynamically or statically
 typed can be very helpful. For example, if you are migrating an existing
 Python codebase to use static types, it's usually easier to migrate by incrementally
@@ -286,7 +284,7 @@ for example, when assigning an empty dictionary to some global value:
 You can teach mypy what type ``my_global_dict`` is meant to have by giving it
 a type hint. For example, if you knew this variable is supposed to be a dict
 of ints to floats, you could annotate it using either variable annotations
-(introduced in Python 3.6 by `PEP 526 <pep526_>`_) or using a comment-based
+(introduced in Python 3.6 by :pep:`526`) or using a comment-based
 syntax like so:
 
 .. code-block:: python
@@ -297,9 +295,6 @@ syntax like so:
    # If you want compatibility with older versions of Python
    my_global_dict = {}  # type: Dict[int, float]
 
-.. _pep526: https://www.python.org/dev/peps/pep-0526/
-
-
 .. _stubs-intro:
 
 Library stubs and typeshed

docs/source/installed_packages.rst

@@ -3,12 +3,12 @@
 Using installed packages
 ========================
 
-`PEP 561 <https://www.python.org/dev/peps/pep-0561/>`__ specifies how to mark
-a package as supporting type checking. Below is a summary of how to create
-PEP 561 compatible packages and have mypy use them in type checking.
+:pep:`561` specifies how to mark a package as supporting type checking.
+Below is a summary of how to create :pep:`561` compatible packages and have
+mypy use them in type checking.
 
-Using PEP 561 compatible packages with mypy
-*******************************************
+Using :pep:`561` compatible packages with mypy
+**********************************************
 
 Generally, you do not need to do anything to use installed packages that
 support typing for the Python executable used to run mypy. Note that most
@@ -30,17 +30,16 @@ imports and custom import hooks.
 If you do not want to use typed packages, use the ``--no-site-packages`` flag
 to disable searching.
 
-Note that stub-only packages (defined in
-`PEP 561 <https://www.python.org/dev/peps/pep-0561/#stub-only-packages>`__)
-cannot be used with ``MYPYPATH``. If you want mypy to find the package, it must
-be installed. For a package ``foo``, the name of the stub-only package
-(``foo-stubs``) is not a legal package name, so mypy will not find it, unless
-it is installed.
+Note that stub-only packages (defined in :pep:`PEP 561: Stub-only Packages
+<561#stub-only-packages>`) cannot be used with ``MYPYPATH``. If you want mypy
+to find the package, it must be installed. For a package ``foo``, the name of
+the stub-only package (``foo-stubs``) is not a legal package name, so mypy
+will not find it, unless it is installed.
 
-Making PEP 561 compatible packages
-**********************************
+Making :pep:`561` compatible packages
+*************************************
 
-PEP 561 notes three main ways to distribute type information. The first is a
+:pep:`561` notes three main ways to distribute type information. The first is a
 package that has only inline type annotations in the code itself. The second is
 a package that ships :ref:`stub files <stub-files>` with type information
 alongside the runtime code. The third method, also known as a "stub only