Skip to content

Commit 47dab6a

Browse files
hoeflingGuido van Rossum
hoefling
authored and
Guido van Rossum
committed
Replace hardcoded links with intersphinx refs in docs (python#7623)
Configured intersphinx extension, replaced external links with intersphinx refs and pep role. Signed-off-by: Oleg Höfling <oleg.hoefling@gmail.com>
1 parent 47093eb commit 47dab6a

23 files changed

+96
-109
lines changed

‎docs/source/additional_features.rst

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,10 @@ of the previous sections.
99
Dataclasses
1010
***********
1111

12-
In Python 3.7, a new ``dataclasses`` module has been added to the standard library.
12+
In Python 3.7, a new :py:mod:`dataclasses` module has been added to the standard library.
1313
This module allows defining and customizing simple boilerplate-free classes.
14-
They can be defined using the ``@dataclasses.dataclass`` decorator:
14+
They can be defined using the :py:func:`@dataclasses.dataclass
15+
<python:dataclasses.dataclass>` decorator:
1516

1617
.. code-block:: python
1718
@@ -65,8 +66,8 @@ class can be used:
6566
6667
val = unbox(BoxedData(42, "<important>")) # OK, inferred type is int
6768
68-
For more information see `official docs <https://docs.python.org/3/library/dataclasses.html>`_
69-
and `PEP 557 <https://www.python.org/dev/peps/pep-0557/>`_.
69+
For more information see :doc:`official docs <python:library/dataclasses>`
70+
and :pep:`557`.
7071

7172
Caveats/Known Issues
7273
====================
@@ -110,7 +111,7 @@ do **not** work:
110111
The attrs package
111112
*****************
112113

113-
`attrs <http://www.attrs.org/en/stable>`_ is a package that lets you define
114+
:doc:`attrs <attrs:index>` is a package that lets you define
114115
classes without writing boilerplate code. Mypy can detect uses of the
115116
package and will generate the necessary method definitions for decorated
116117
classes using the type annotations it finds.
@@ -176,7 +177,7 @@ Caveats/Known Issues
176177
will complain about not understanding the argument and the type annotation in
177178
``__init__`` will be replaced by ``Any``.
178179

179-
* `Validator decorators <http://www.attrs.org/en/stable/examples.html#validators>`_
180+
* :ref:`Validator decorators <attrs:examples_validators>`
180181
and `default decorators <http://www.attrs.org/en/stable/examples.html#defaults>`_
181182
are not type-checked against the attribute they are setting/validating.
182183

‎docs/source/cheat_sheet.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@
33
Type hints cheat sheet (Python 2)
44
=================================
55

6-
This document is a quick cheat sheet showing how the
7-
`PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ type
6+
This document is a quick cheat sheet showing how the :pep:`484` type
87
language represents various common types in Python 2.
98

109
.. note::

‎docs/source/cheat_sheet_py3.rst

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@
33
Type hints cheat sheet (Python 3)
44
=================================
55

6-
This document is a quick cheat sheet showing how the
7-
`PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ type
6+
This document is a quick cheat sheet showing how the :pep:`484` type
87
annotation notation represents various common types in Python 3.
98

109
.. note::
@@ -18,9 +17,8 @@ annotation notation represents various common types in Python 3.
1817
Variables
1918
*********
2019

21-
Python 3.6 introduced a syntax for annotating variables in
22-
`PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ and
23-
we use it in most examples.
20+
Python 3.6 introduced a syntax for annotating variables in :pep:`526`
21+
and we use it in most examples.
2422

2523
.. code-block:: python
2624

‎docs/source/command_line.rst

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ imports.
7878

7979
``--namespace-packages``
8080
This flag enables import discovery to use namespace packages (see
81-
`PEP 420`_). In particular, this allows discovery of imported
81+
:pep:`420`). In particular, this allows discovery of imported
8282
packages that don't have an ``__init__.py`` (or ``__init__.pyi``)
8383
file.
8484

@@ -127,23 +127,23 @@ imports.
127127
see :ref:`Following imports <follow-imports>`.
128128

129129
``--python-executable EXECUTABLE``
130-
This flag will have mypy collect type information from `PEP 561`_
130+
This flag will have mypy collect type information from :pep:`561`
131131
compliant packages installed for the Python executable ``EXECUTABLE``.
132-
If not provided, mypy will use PEP 561 compliant packages installed for
132+
If not provided, mypy will use :pep:`561` compliant packages installed for
133133
the Python executable running mypy.
134134

135-
See :ref:`installed-packages` for more on making PEP 561 compliant packages.
135+
See :ref:`installed-packages` for more on making :pep:`561` compliant packages.
136136

137137
``--no-site-packages``
138-
This flag will disable searching for `PEP 561`_ compliant packages. This
138+
This flag will disable searching for :pep:`561` compliant packages. This
139139
will also disable searching for a usable Python executable.
140140

141141
Use this flag if mypy cannot find a Python executable for the version of
142-
Python being checked, and you don't need to use PEP 561 typed packages.
142+
Python being checked, and you don't need to use :pep:`561` typed packages.
143143
Otherwise, use ``--python-executable``.
144144

145145
``--no-silence-site-packages``
146-
By default, mypy will suppress any error messages generated within PEP 561
146+
By default, mypy will suppress any error messages generated within :pep:`561`
147147
compliant packages. Adding this flag will disable this behavior.
148148

149149

@@ -165,7 +165,7 @@ For more information on how to use these flags, see :ref:`version_and_platform_c
165165
``--py2`` flags are aliases for ``--python-version 2.7``.
166166

167167
This flag will attempt to find a Python executable of the corresponding
168-
version to search for `PEP 561`_ compliant packages. If you'd like to
168+
version to search for :pep:`561` compliant packages. If you'd like to
169169
disable this, use the ``--no-site-packages`` flag (see
170170
:ref:`import-discovery` for more details).
171171

@@ -178,7 +178,7 @@ For more information on how to use these flags, see :ref:`version_and_platform_c
178178
default to using whatever operating system you are currently using.
179179

180180
The ``PLATFORM`` parameter may be any string supported by
181-
`sys.platform <https://docs.python.org/3/library/sys.html#sys.platform>`_.
181+
:py:data:`sys.platform`.
182182

183183
.. _always-true:
184184

@@ -680,8 +680,4 @@ Miscellaneous
680680
have many scripts that import a large package, the behavior enabled
681681
by this flag is often more convenient.)
682682

683-
.. _PEP 420: https://www.python.org/dev/peps/pep-0420/
684-
685-
.. _PEP 561: https://www.python.org/dev/peps/pep-0561/
686-
687683
.. _lxml: https://pypi.org/project/lxml/

‎docs/source/common_issues.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -438,8 +438,7 @@ to have Python 2.7 installed to perform this check.
438438

439439
To target a different operating system, use the ``--platform PLATFORM`` flag.
440440
For example, to verify your code typechecks if it were run in Windows, pass
441-
in ``--platform win32``. See the documentation for
442-
`sys.platform <https://docs.python.org/3/library/sys.html#sys.platform>`_
441+
in ``--platform win32``. See the documentation for :py:data:`sys.platform`
443442
for examples of valid platform parameters.
444443

445444
.. _reveal-type:

‎docs/source/conf.py

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
# Add any Sphinx extension module names here, as strings. They can be
3131
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
3232
# ones.
33-
extensions = []
33+
extensions = ['sphinx.ext.intersphinx']
3434

3535
# Add any paths that contain templates here, relative to this directory.
3636
templates_path = ['_templates']
@@ -266,3 +266,11 @@
266266
#texinfo_no_detailmenu = False
267267

268268
rst_prolog = '.. |...| unicode:: U+2026 .. ellipsis\n'
269+
270+
intersphinx_mapping = {
271+
'python': ('https://docs.python.org/3', None),
272+
'six': ('https://six.readthedocs.io', None),
273+
'attrs': ('http://www.attrs.org/en/stable', None),
274+
'cython': ('http://docs.cython.org/en/latest', None),
275+
'monkeytype': ('https://monkeytype.readthedocs.io/en/latest', None),
276+
}

‎docs/source/config_file.rst

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,9 @@ Config file format
2929
******************
3030

3131
The configuration file format is the usual
32-
`ini file <https://docs.python.org/3.6/library/configparser.html>`_
33-
format. It should contain section names in square brackets and flag
34-
settings of the form `NAME = VALUE`. Comments start with ``#``
35-
characters.
32+
:doc:`ini file <python:library/configparser>` format. It should contain
33+
section names in square brackets and flag settings of the form
34+
`NAME = VALUE`. Comments start with ``#`` characters.
3635

3736
- A section named ``[mypy]`` must be present. This specifies
3837
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
357356
:ref:`both per-module and globally <config-file-import-discovery-per-module>`.
358357

359358
``namespace_packages`` (bool, default False)
360-
Enables PEP 420 style namespace packages. See :ref:`the
359+
Enables :pep:`420` style namespace packages. See :ref:`the
361360
corresponding flag <import-discovery>` for more information.
362361

363362
``python_executable`` (string)
@@ -367,7 +366,7 @@ a list of import discovery options that may be used
367366
the executable used to run mypy.
368367

369368
``no_silence_site_packages`` (bool, default False)
370-
Enables reporting error messages generated within PEP 561 compliant packages.
369+
Enables reporting error messages generated within :pep:`561` compliant packages.
371370
Those error messages are suppressed by default, since you are usually
372371
not able to control errors in 3rd party code.
373372

@@ -379,9 +378,8 @@ a list of import discovery options that may be used
379378

380379
``files`` (string)
381380
A comma-separated list of paths which should be checked by mypy if none are given on the command
382-
line. Supports recursive file globbing using
383-
[the glob library](https://docs.python.org/3/library/glob.html), where `*` (e.g. `*.py`) matches
384-
files in the current directory and `**/` (e.g. `**/*.py`) matches files in any directories below
381+
line. Supports recursive file globbing using :doc:`library/glob`, where ``*`` (e.g. ``*.py``) matches
382+
files in the current directory and ``**/`` (e.g. ``**/*.py``) matches files in any directories below
385383
the current one. User home directory and environment variables will be expanded.
386384

387385

‎docs/source/error_code_list.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -542,8 +542,8 @@ Check instantiation of abstract classes [abstract]
542542

543543
Mypy generates an error if you try to instantiate an abstract base
544544
class (ABC). An abtract base class is a class with at least one
545-
abstract method or attribute. (See also `Python
546-
abc module documentation <https://docs.python.org/3/library/abc.html>`_.)
545+
abstract method or attribute. (See also :doc:`Python
546+
abc module documentation <python:library/abc>`)
547547

548548
Sometimes a class is made accidentally abstract, often due to an
549549
unimplemented abstract method. In a case like this you need to provide

‎docs/source/existing_code.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ These steps will get you started with mypy on an existing codebase:
2020

2121
5. Write annotations as you modify existing code and write new code
2222

23-
6. Use MonkeyType or PyAnnotate to automatically annotate legacy code
23+
6. Use :doc:`monkeytype:index` or `PyAnnotate`_ to automatically annotate legacy code
2424

2525
We discuss all of these points in some detail below, and a few optional
2626
follow-up steps.
@@ -145,8 +145,7 @@ Automate annotation of legacy code
145145

146146
There are tools for automatically adding draft annotations
147147
based on type profiles collected at runtime. Tools include
148-
`MonkeyType <https://github.com/Instagram/MonkeyType>`_
149-
(Python 3) and `PyAnnotate <https://github.com/dropbox/pyannotate>`_
148+
:doc:`monkeytype:index` (Python 3) and `PyAnnotate`_
150149
(type comments only).
151150

152151
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
177176
for all functions in certain modules to avoid accidentally introducing
178177
code that won't be type checked. Refer to :ref:`command-line` for the
179178
details.
179+
180+
.. _PyAnnotate: https://github.com/dropbox/pyannotate

‎docs/source/extending_mypy.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,12 +43,12 @@ Extending mypy using plugins
4343
Python is a highly dynamic language and has extensive metaprogramming
4444
capabilities. Many popular libraries use these to create APIs that may
4545
be more flexible and/or natural for humans, but are hard to express using
46-
static types. Extending the PEP 484 type system to accommodate all existing
46+
static types. Extending the :pep:`484` type system to accommodate all existing
4747
dynamic patterns is impractical and often just impossible.
4848

4949
Mypy supports a plugin system that lets you customize the way mypy type checks
5050
code. This can be useful if you want to extend mypy so it can type check code
51-
that uses a library that is difficult to express using just PEP 484 types.
51+
that uses a library that is difficult to express using just :pep:`484` types.
5252

5353
The plugin system is focused on improving mypy's understanding
5454
of *semantics* of third party frameworks. There is currently no way to define
@@ -139,7 +139,7 @@ Current list of plugin hooks
139139
****************************
140140

141141
**get_type_analyze_hook()** customizes behaviour of the type analyzer.
142-
For example, PEP 484 doesn't support defining variadic generic types:
142+
For example, :pep:`484` doesn't support defining variadic generic types:
143143

144144
.. code-block:: python
145145

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy