Skip to content

Commit

Permalink
Fix all the missing references found within the docs (#15875)
Browse files Browse the repository at this point in the history
Fixes #13196.

Enable the nit-picky mode on sphinx-build in tox, as this will
facilitate the detection of potential issues related to missing
references.
  • Loading branch information
atugushev authored Aug 15, 2023
1 parent b49be10 commit fda7a46
Show file tree
Hide file tree
Showing 4 changed files with 13 additions and 13 deletions.
2 changes: 1 addition & 1 deletion docs/source/error_code_list.rst
Original file line number Diff line number Diff line change
Expand Up @@ -835,7 +835,7 @@ ellipsis ``...``, a docstring, and a ``raise NotImplementedError`` statement.
Check the target of NewType [valid-newtype]
-------------------------------------------

The target of a :py:func:`NewType <typing.NewType>` definition must be a class type. It can't
The target of a :py:class:`~typing.NewType` definition must be a class type. It can't
be a union type, ``Any``, or various other special types.

You can also get this error if the target has been imported from a
Expand Down
18 changes: 9 additions & 9 deletions docs/source/more_types.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ More types
==========

This section introduces a few additional kinds of types, including :py:data:`~typing.NoReturn`,
:py:func:`NewType <typing.NewType>`, and types for async code. It also discusses
:py:class:`~typing.NewType`, and types for async code. It also discusses
how to give functions more precise types using overloads. All of these are only
situationally useful, so feel free to skip this section and come back when you
have a need for some of them.
Expand All @@ -11,7 +11,7 @@ Here's a quick summary of what's covered here:

* :py:data:`~typing.NoReturn` lets you tell mypy that a function never returns normally.

* :py:func:`NewType <typing.NewType>` lets you define a variant of a type that is treated as a
* :py:class:`~typing.NewType` lets you define a variant of a type that is treated as a
separate type by mypy but is identical to the original type at runtime.
For example, you can have ``UserId`` as a variant of ``int`` that is
just an ``int`` at runtime.
Expand Down Expand Up @@ -75,7 +75,7 @@ certain values from base class instances. Example:
...
However, this approach introduces some runtime overhead. To avoid this, the typing
module provides a helper object :py:func:`NewType <typing.NewType>` that creates simple unique types with
module provides a helper object :py:class:`~typing.NewType` that creates simple unique types with
almost zero runtime overhead. Mypy will treat the statement
``Derived = NewType('Derived', Base)`` as being roughly equivalent to the following
definition:
Expand Down Expand Up @@ -113,12 +113,12 @@ implicitly casting from ``UserId`` where ``int`` is expected. Examples:
num: int = UserId(5) + 1
:py:func:`NewType <typing.NewType>` accepts exactly two arguments. The first argument must be a string literal
:py:class:`~typing.NewType` accepts exactly two arguments. The first argument must be a string literal
containing the name of the new type and must equal the name of the variable to which the new
type is assigned. The second argument must be a properly subclassable class, i.e.,
not a type construct like :py:data:`~typing.Union`, etc.

The callable returned by :py:func:`NewType <typing.NewType>` accepts only one argument; this is equivalent to
The callable returned by :py:class:`~typing.NewType` accepts only one argument; this is equivalent to
supporting only one constructor accepting an instance of the base class (see above).
Example:

Expand All @@ -139,12 +139,12 @@ Example:
tcp_packet = TcpPacketId(127, 0) # Fails in type checker and at runtime
You cannot use :py:func:`isinstance` or :py:func:`issubclass` on the object returned by
:py:func:`~typing.NewType`, nor can you subclass an object returned by :py:func:`~typing.NewType`.
:py:class:`~typing.NewType`, nor can you subclass an object returned by :py:class:`~typing.NewType`.

.. note::

Unlike type aliases, :py:func:`NewType <typing.NewType>` will create an entirely new and
unique type when used. The intended purpose of :py:func:`NewType <typing.NewType>` is to help you
Unlike type aliases, :py:class:`~typing.NewType` will create an entirely new and
unique type when used. The intended purpose of :py:class:`~typing.NewType` is to help you
detect cases where you accidentally mixed together the old base type and the
new derived type.

Expand All @@ -160,7 +160,7 @@ You cannot use :py:func:`isinstance` or :py:func:`issubclass` on the object retu
name_by_id(3) # ints and UserId are synonymous
But a similar example using :py:func:`NewType <typing.NewType>` will not typecheck:
But a similar example using :py:class:`~typing.NewType` will not typecheck:

.. code-block:: python
Expand Down
4 changes: 2 additions & 2 deletions docs/source/runtime_troubles.rst
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ required to be valid Python syntax. For more details, see :pep:`563`.

* :ref:`type aliases <type-aliases>`;
* :ref:`type narrowing <type-narrowing>`;
* type definitions (see :py:class:`~typing.TypeVar`, :py:func:`~typing.NewType`, :py:class:`~typing.NamedTuple`);
* type definitions (see :py:class:`~typing.TypeVar`, :py:class:`~typing.NewType`, :py:class:`~typing.NamedTuple`);
* base classes.

.. code-block:: python
Expand Down Expand Up @@ -263,7 +263,7 @@ If your subclass is also generic, you can use the following:
reveal_type(task_queue.get()) # Reveals str
In Python 3.9, we can just inherit directly from ``Queue[str]`` or ``Queue[T]``
since its :py:class:`queue.Queue` implements :py:meth:`__class_getitem__`, so
since its :py:class:`queue.Queue` implements :py:meth:`~object.__class_getitem__`, so
the class object can be subscripted at runtime without issue.

Using types defined in stubs but not at runtime
Expand Down
2 changes: 1 addition & 1 deletion tox.ini
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ passenv =
VERIFY_MYPY_ERROR_CODES
deps = -rdocs/requirements-docs.txt
commands =
sphinx-build -d "{toxworkdir}/docs_doctree" docs/source "{toxworkdir}/docs_out" --color -W -bhtml {posargs}
sphinx-build -n -d "{toxworkdir}/docs_doctree" docs/source "{toxworkdir}/docs_out" --color -W -bhtml {posargs}
python -c 'import pathlib; print("documentation available under file://\{0\}".format(pathlib.Path(r"{toxworkdir}") / "docs_out" / "index.html"))'

[testenv:lint]
Expand Down

0 comments on commit fda7a46

Please sign in to comment.