Crossreferences to standard library in mypy docs, part 3 #7677

hoefling · 2019-10-09T23:40:19Z

Added references to the following documents:

error_code_list.rst
error_code_list2.rst
extending_mypy.rst
faq.rst
final_attrs.rst
getting_started.rst

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

hoefling · 2019-10-09T23:43:58Z

docs/source/error_code_list.rst

@@ -415,11 +415,11 @@ Example:
    # Error: Dict entry 0 has incompatible type "str": "str"; expected "str": "int"  [dict-item]
    d: Dict[str, int] = {'key': 'value'}

-Check TypedDict items [typeddict-item]
--------------------------------------
+Check ``TypedDict`` items [typeddict-item]


Please advise whether verbatim texts in section headers are useful. This renders as:

The side effect is also verbatim text in the table of contents:

I think it looks better without the heavy formatting. TBH I find most CSS styling for code blocks over the top, and red is particularly bad in a heading. I also don't care about the box (or shading in other CSS setups).

Agree. IMO the best solution is simply use monospaced font for verbatim formatting like Python stdlib docs do that (and afaik Javadoc too). If you don't mind, I will also replace other occurences of verbatim text in section titles in this PR.

hoefling · 2019-10-09T23:46:12Z

docs/source/extending_mypy.rst


-**get_attribute_hook** overrides instance member field lookups and property
+**get_attribute_hook()** overrides instance member field lookups and property


All other paragraphs use parentheses in hook names, I suppose they were omitted by mistake here.

hoefling · 2019-10-09T23:48:11Z

docs/source/getting_started.rst

 module. For example, to indicate that some function can accept a list of
-strings, use the ``List`` type from the ``typing`` module:


Second change unrelated to referencing. IMO with the List reference, there's no need to mention the module again - it's also referenced one line above that. What do you think?

+1

(PS. When commenting on a diff chunk, please attach the comment to the last line, so the context in email or in the Conversation view is clearer. I think you can now also shift-click to attach a comment to a range of lines.)

hoefling · 2019-10-09T23:51:11Z

docs/source/faq.rst

@@ -164,7 +163,7 @@ monkey patching of methods.
 How is mypy different from Cython?
 **********************************

-`Cython :doc:<cython:index>` is a variant of Python that supports
+:doc:`Cython <cython:index>` is a variant of Python that supports


Fixing my own errors here. No idea why Sphinx didn't catch this on build.

Didn't you have to run it with special flags to check errors?

I did (using sphinx-build -WEan), however Sphinx ignores markup errors and just renders the text as-is. Neither does doc8 nor restructuredtext-lint, sadly.

hoefling · 2019-10-09T23:53:50Z

docs/source/extending_mypy.rst

@@ -98,7 +98,7 @@ High-level overview
 *******************

 Every entry point function should accept a single string argument
-that is a full mypy version and return a subclass of ``mypy.plugins.Plugin``:


One of two changes in this PR that are not related to referencing, typo fix.

gvanrossum

Didn't mean to send every comment as a separate email. And I'm not done, but wanted to reply to all your questions first.

gvanrossum · 2019-10-10T00:24:30Z

docs/source/getting_started.rst

 module. For example, to indicate that some function can accept a list of
-strings, use the ``List`` type from the ``typing`` module:


+1

(PS. When commenting on a diff chunk, please attach the comment to the last line, so the context in email or in the Conversation view is clearer. I think you can now also shift-click to attach a comment to a range of lines.)

gvanrossum

Looks good, except I think you should get rid of all the code markup in headings.

gvanrossum · 2019-10-10T02:33:28Z

docs/source/faq.rst

@@ -164,7 +163,7 @@ monkey patching of methods.
 How is mypy different from Cython?
 **********************************

-`Cython :doc:<cython:index>` is a variant of Python that supports
+:doc:`Cython <cython:index>` is a variant of Python that supports


Didn't you have to run it with special flags to check errors?

…, final_attrs.rst Signed-off-by: Oleg Höfling <[email protected]>

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

hoefling commented Oct 9, 2019

View reviewed changes

gvanrossum reviewed Oct 10, 2019

View reviewed changes

hoefling added 2 commits October 10, 2019 18:27

revisited error_code{s,_list,_list2}.rst, extending_mypy.rst, faq.rst…

6121331

…, final_attrs.rst Signed-off-by: Oleg Höfling <[email protected]>

revisited getting_started.rst

c3a29f2

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

hoefling force-pushed the stdlib-crossref-3 branch from 829e8fc to bfdfc3d Compare October 10, 2019 17:03

remove verbatim titles

e497d2d

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

hoefling force-pushed the stdlib-crossref-3 branch from bfdfc3d to e497d2d Compare October 10, 2019 17:07

gvanrossum merged commit 742d33a into python:master Oct 10, 2019

hoefling deleted the stdlib-crossref-3 branch October 10, 2019 21:36


		get_attribute_hook overrides instance member field lookups and property
		get_attribute_hook() overrides instance member field lookups and property

		module. For example, to indicate that some function can accept a list of
		strings, use the ``List`` type from the ``typing`` module:

Uh oh!

Crossreferences to standard library in mypy docs, part 3 #7677

Crossreferences to standard library in mypy docs, part 3 #7677

Uh oh!

Conversation

hoefling commented Oct 9, 2019

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!

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!

gvanrossum left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!