Replace hardcoded links with intersphinx refs in docs

[hoefling]

This is the first part of adding referencing to mypys docs (second part being #7624). I have configured intersphinx and replaced hardcoded links with intersphinx references. IMO this has a huge benefit of maintaining links consistency: while the hardcoded link is unmanageable (for example, currently the link https://pythonhosted.org/six/#six.with_metaclass points to nowhere since six documentation has moved to https://six.readthedocs.io), the intersphinx refs are checked implicitly - if a ref is dead, Sphinx will emit a warning when building docs¹. intersphinx is an extension that is included in Sphinx by default, so no extra dependencies needed.

Another advantage is the referencing simplicity: for example, instead of writing

any string supported by `sys.platform <https://docs.python.org/3/library/sys.html#sys.platform>`_

rendered as

you do

any string supported by :py:data:`sys.platform`

rendered as

which is IMO a lot less work when typing and has a different style when rendered, pointing out the fact that the link leads to a library documentation.

Also, Sphinx has a :pep: role that generates links to PEP pages, so e.g.

PEP 561 <https://www.python.org/dev/peps/pep-0561/>`__ specifies ...

rendered as

becomes

:pep:`561` specifies ...

rendered as

¹ Of course, there's the linkcheck builder that checks for dead references, but it has to be run explicitly, so it's still beneficial to reduce the amount of hardcoded links to a minimum. Also, linkcheck doesn't check for the link formatting: if one e.g. uses markdown instead of ReST to format the link, this will render wrong, but linkcheck won't complain.

[gvanrossum]

I think this is a brilliant idea and will review shortly.

[gvanrossum]

I'll just land this.

[gvanrossum]

@hoefling Is it expected that the mouse-over text for the new links is always "(in Python v3.7)"? This seems a little cryptic, and I'm not sure where it comes from (I suppose this is hardcoded in sphinx interlink?)

[hoefling]

Yes, looks like it's hardcoded in intersphinx code:

https://github.com/sphinx-doc/sphinx/blob/7faeb793e2e16cde4e5759443fb7f84efddcd9ea/sphinx/ext/intersphinx.py#L299-L303

I imagine this can be customized though - a custom extension that walks over document nodes and adapts reftitle to something more meaningful.

Also, thank you for the advices in the other issue - these are golden, especially the hint with no restrictions on the line length in docs! I was concerned with keeping the lines under 99 chars which resulted in lots of unnecessary changes. Knowing that now, I'm sure this will reduce the amount of diffs drastically.

[gvanrossum]

Heh, I guess we can live with the hardcoded mouse-over until more people complain. :-)