[docs] use sphinx :pep: role

.travis.yml

@@ -53,7 +53,7 @@ jobs:
   - name: "check documentation build"
     python: 3.7
     env:
-    - TOXENV=docs
+    - TOXENV="docs,linkcheck"
   # Disabled because of some pip bug? See #6716
   # - name: "check dev environment builds"
   #   python: 3.7

docs/source/command_line.rst

@@ -77,7 +77,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.
 
@@ -126,7 +126,7 @@ 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
     the Python executable running mypy.
@@ -135,16 +135,16 @@ imports.
     This flag will attempt to set ``--python-version`` if not already set.
 
 ``--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.
     Otherwise, use ``--python-executable``.
 
 ``--no-silence-site-packages``
-    By default, mypy will suppress any error messages generated within PEP 561
-    compliant packages. Adding this flag will disable this behavior.
+    By default, mypy will suppress any error messages generated within
+    :pep:`561` compliant packages. Adding this flag will disable this behavior.
 
 
 .. _platform-configuration:
@@ -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).
 
@@ -606,8 +606,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/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
 **************************************************

tox.ini

@@ -6,7 +6,8 @@ envlist = py35,
           py37,
           lint,
           type,
-          docs
+          docs,
+          linkcheck
 isolated_build = true
 
 [testenv]
@@ -34,6 +35,12 @@ basepython = python3.7
 deps = -rdocs/requirements-docs.txt
 commands = sphinx-build -d "{toxworkdir}/docs_doctree" docs/source "{toxworkdir}/docs_out" --color -W -bhtml {posargs}
 
+[testenv:linkcheck]
+description = invoke sphinx-build to check hyperlinks in the docs
+basepython = python3.7
+deps = -rdocs/requirements-docs.txt
+commands = sphinx-build -d "{toxworkdir}/docs_doctree" docs/source "{toxworkdir}/docs_out" --color -W -blinkcheck {posargs}
+
 [testenv:dev]
 description = generate a DEV environment, that has all project libraries
 usedevelop = True