Use Sphinx' intersphinx extension to link to Python docs

[Jannis Leidel]

This would apply to about 50 links in the docs that are manually maintained and might change in the future.

[Jannis Leidel]

To be a bit more specific, the extension allows to refer to other modules and references using the same notation we use for internal links.

​http://sphinx.pocoo.org/latest/ext/intersphinx.html

E.g. this would be possible:

Doctests use Python's standard :mod:`doctest` module, which searches your
docstrings for statements that resemble a session of the Python interactive
interpreter.

or

For example, let's write a template tag, ``{% current_time %}``, that displays
the current date/time, formatted according to a parameter given in the tag, in
:func:`strftime syntax<time.strftime>`.

[Ramiro Morales]

Sounds like a great idea, relatively simple to implement and using an extension already shipped with Sphinx since version 0.5.

[Aymeric Augustin]

Minor problem: this creates an inconsistency in the HTML output.

Here is the HTML (indented for readability), I'm also attaching a screenshot:

<p>
    If you need help with regular expressions, see
    <a class="reference external" href="http://en.wikipedia.org/wiki/Regular_expression">Wikipedia's entry</a>
    and
    <a class="reference external" href="http://docs.python.org/library/re.html#module-re" title="(in Python v2.7)">
        <tt class="xref py py-mod docutils literal">
            <span class="pre">Python's</span>
            <span class="pre">documentation</span>
        </tt>
    </a>
    . Also, the O'Reilly book "Mastering Regular Expressions" by Jeffrey Friedl is fantastic.
</p>

[Aymeric Augustin]

I didn't find how to add anchors for links that point to a given section. I'm not sure it's possible with intersphinx.

I'm attaching a patch that fixes all the other links.

[Jannis Leidel]

This shouldn't use the dev version of Python's docs since that's 3.X and clearly not the target version of Django.

[Aymeric Augustin]

New patch:

• explicitly uses 2.7 docs (the previous version used the default version, currently 2.7)
• uses :pep: for links to PEPs,
• links to PEP 3333 instead of 333
• removes all links to pages of www.python.org, except the home page,
• also uses intersphinx for links to sphinx's docs,
• adds a note about intersphinx in the documentation guidelines.

[Jannis Leidel]

Awesome!

[Simon Meers]

Thanks for the patch Aymeric. I was about to check it in when I discovered some links don't render correctly; e.g.:

"To get started contributing, you’ll want to read the reStructuredText Primer <rst-primer>. After that, you’ll want to read about the Sphinx-specific markup <sphinxmarkup> that’s used to manage metadata, indexing, and cross-references."

-- actually rendered like that. Others (e.g. peps) seems to work fine. Am I missing some configuration to fix these ones, or is the syntax incorrect?

Also, do we care that the links render as displayed in the uploaded screenshot? (which I've confirmed locally).

[Aymeric Augustin]

There was a typo on the two links that didn't render correctly — a missing :ref:. This typo didn't occur anywhere else in the patch.

About the style issue, in fact, it isn't specific to intersphinx. Here's how sphinx works :

• for links to objects (modules, classes, functions, etc): they get the "technical" link style;
• for links to references: they get the regular link style.

The problem appeared with the conversion to intersphinx links because it created links to objects with an alternate text. I have tweaked the wording so that the text of each link is the name of the referenced object; that makes the look'n'feel consistent with the rest of the documentation.

While I was proof-reading, I've:

• added more links, especially in topics/testing
• added even more semantic markup (:rfc: and :mimetype:) — and verified these changes carefully
• used ~ to shorten references to objects appropriately

This patch has grown a bit beyond the initial scope, sorry. I hope it's still acceptable — It's just semantic goodness :)

[Ramiro Morales]

In [16720]:

Converted links to external topics so they use intersphinx extension markup.

This allows to make these links more resilent to changes in the target URLs.
Thanks Jannis for the report and Aymeric Augustin for the patch.

Fixes #16586.