Opened 5 years ago

Closed 5 years ago

#16586 closed Cleanup/optimization (fixed)

Use Sphinx' intersphinx extension to link to Python docs

Reported by: Jannis Leidel Owned by: Aymeric Augustin
Component: Documentation Version: 1.3
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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

Attachments (4)

Screen Shot 2011-08-07 at 21.09.11.png (12.1 KB) - added by Aymeric Augustin 5 years ago.
16586.diff (36.5 KB) - added by Aymeric Augustin 5 years ago.
16586.2.patch (51.8 KB) - added by Aymeric Augustin 5 years ago.
16586.3.patch (78.4 KB) - added by Aymeric Augustin 5 years ago.

Download all attachments as: .zip

Change History (15)

comment:1 Changed 5 years ago by 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>`.

comment:2 Changed 5 years ago by Ramiro Morales

Triage Stage: UnreviewedAccepted

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

comment:3 Changed 5 years ago by Aymeric Augustin

Owner: changed from nobody to Aymeric Augustin

comment:4 Changed 5 years ago by 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>

Changed 5 years ago by Aymeric Augustin

comment:5 Changed 5 years ago by 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.

Changed 5 years ago by Aymeric Augustin

Attachment: 16586.diff added

comment:6 Changed 5 years ago by Jannis Leidel

Patch needs improvement: set

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

comment:7 Changed 5 years ago by Aymeric Augustin

Patch needs improvement: unset

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.

Changed 5 years ago by Aymeric Augustin

Attachment: 16586.2.patch added

comment:8 Changed 5 years ago by Jannis Leidel

Triage Stage: AcceptedReady for checkin

Awesome!

comment:9 Changed 5 years ago by Simon Meers

Has patch: set
Patch needs improvement: set

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).

comment:10 Changed 5 years ago by Aymeric Augustin

Patch needs improvement: unset

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 :)

Changed 5 years ago by Aymeric Augustin

Attachment: 16586.3.patch added

comment:11 Changed 5 years ago by Ramiro Morales

Resolution: fixed
Status: newclosed

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.

Note: See TracTickets for help on using tickets.
Back to Top