Crossreferences to standard library in mypy docs, part 2 #7660

hoefling · 2019-10-08T22:34:47Z

Added references to the following documents:

builtin_types.rst
common_issues.rst
config_file.rst
dynamic_typing.rst

This is part of splitting up the changes in #7624 into more readable PRs.

docs/source/common_issues.rst

hoefling · 2019-10-08T22:40:11Z

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


I suppose the verbatim formatting was forgotten here, so added the Optional ref as well.

hoefling · 2019-10-08T22:44:03Z

docs/source/config_file.rst

    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


Please advise here. Both links lead to the same target: the glob module docs, but are rendered differently:

vs

I like the second better. So +1 to the change. (Do we use this :doc: style elsewhere, and does it get rendered so longwindedly there too? I think it's not needed.)

There are a few :doc: roles that refer to standard library modules:

mypy/docs/source/additional_features.rst

Line 69 in c95ecc1

For more information see :doc:`official docs <python:library/dataclasses>`

mypy/docs/source/class_basics.rst

Line 235 in c95ecc1

Mypy supports Python :doc:`abstract base classes <library/abc>` (ABCs). Abstract classes

mypy/docs/source/config_file.rst

Line 32 in c95ecc1

:doc:`ini file <python:library/configparser>` format. It should contain

mypy/docs/source/error_code_list.rst

Lines 545 to 546 in c95ecc1

abstract method or attribute. (See also :doc:`Python

abc module documentation <python:library/abc>`)

Do you suggest to replace them with the appropriate :mod: role?

It doesn't seem necessary, since those other places all specify link text.

We cannot hope to strive for 100% consistency everywhere.

docs/source/config_file.rst

hoefling · 2019-10-08T22:49:17Z

docs/source/dynamic_typing.rst

-You can use ``cast()`` (see chapter :ref:`casts`) or ``isinstance`` to
-go from a general type such as ``object`` to a more specific
-type (subtype) such as ``int``.  ``cast()`` is not needed with
+You can use :py:func:`~typing.cast` (see chapter :ref:`casts`) or :py:func:`isinstance` to


I have altered the rendering by including the parentheses to isinstance. Before:

After:

Both are functions - shouldn't both have parentheses in this case?

+1. The only time it's better not to add () to a function is when we're talking about the function object (e.g. in the context of creating an alias or accessing attributes).

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

gvanrossum

Will merge as-is.

docs/source/common_issues.rst

gvanrossum · 2019-10-09T18:32:05Z

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


gvanrossum · 2019-10-09T18:34:22Z

docs/source/config_file.rst

    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


I like the second better. So +1 to the change. (Do we use this :doc: style elsewhere, and does it get rendered so longwindedly there too? I think it's not needed.)

docs/source/config_file.rst

gvanrossum · 2019-10-09T18:34:57Z

docs/source/dynamic_typing.rst

-You can use ``cast()`` (see chapter :ref:`casts`) or ``isinstance`` to
-go from a general type such as ``object`` to a more specific
-type (subtype) such as ``int``.  ``cast()`` is not needed with
+You can use :py:func:`~typing.cast` (see chapter :ref:`casts`) or :py:func:`isinstance` to


+1. The only time it's better not to add () to a function is when we're talking about the function object (e.g. in the context of creating an alias or accessing attributes).

hoefling commented Oct 8, 2019

View reviewed changes

hoefling added 3 commits October 9, 2019 01:15

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

e4333f5

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

fixed null device name

6347c08

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

revisited dynamic_typing.rst

943f159

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

hoefling force-pushed the stdlib-crossref-2 branch from 01c55cd to 943f159 Compare October 8, 2019 23:15

gvanrossum approved these changes Oct 9, 2019

View reviewed changes

gvanrossum merged commit 54e3452 into python:master Oct 9, 2019

hoefling deleted the stdlib-crossref-2 branch October 9, 2019 20:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Crossreferences to standard library in mypy docs, part 2 #7660

Crossreferences to standard library in mypy docs, part 2 #7660

Uh oh!

hoefling commented Oct 8, 2019

Uh oh!

Uh oh!

hoefling Oct 8, 2019

Uh oh!

gvanrossum Oct 9, 2019

Uh oh!

hoefling Oct 8, 2019

Uh oh!

gvanrossum Oct 9, 2019

Uh oh!

hoefling Oct 9, 2019

Uh oh!

gvanrossum Oct 9, 2019

Uh oh!

Uh oh!

hoefling Oct 8, 2019

Uh oh!

gvanrossum Oct 9, 2019

Uh oh!

gvanrossum left a comment

Uh oh!

Uh oh!

gvanrossum Oct 9, 2019

Uh oh!

gvanrossum Oct 9, 2019

Uh oh!

Uh oh!

gvanrossum Oct 9, 2019

Uh oh!

Uh oh!

	abstract method or attribute. (See also :doc:`Python
	abc module documentation <python:library/abc>`)

Uh oh!

Crossreferences to standard library in mypy docs, part 2 #7660

Crossreferences to standard library in mypy docs, part 2 #7660

Uh oh!

Conversation

hoefling commented Oct 8, 2019

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!