Code

Opened 3 years ago

Closed 3 years ago

#16586 closed Cleanup/optimization (fixed)

Use Sphinx' intersphinx extension to link to Python docs

Reported by: jezdez Owned by: aaugustin
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 aaugustin 3 years ago.
16586.diff (36.5 KB) - added by aaugustin 3 years ago.
16586.2.patch (51.8 KB) - added by aaugustin 3 years ago.
16586.3.patch (78.4 KB) - added by aaugustin 3 years ago.

Download all attachments as: .zip

Change History (15)

comment:1 Changed 3 years ago by jezdez

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 3 years ago by ramiro

  • Triage Stage changed from Unreviewed to Accepted

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

comment:3 Changed 3 years ago by aaugustin

  • Owner changed from nobody to aaugustin

comment:4 Changed 3 years ago by aaugustin

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 3 years ago by aaugustin

comment:5 Changed 3 years ago by aaugustin

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 3 years ago by aaugustin

comment:6 Changed 3 years ago by jezdez

  • 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 3 years ago by aaugustin

  • 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 3 years ago by aaugustin

comment:8 Changed 3 years ago by jezdez

  • Triage Stage changed from Accepted to Ready for checkin

Awesome!

comment:9 Changed 3 years ago by DrMeers

  • 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 3 years ago by aaugustin

  • 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 3 years ago by aaugustin

comment:11 Changed 3 years ago by ramiro

  • Resolution set to fixed
  • Status changed from new to closed

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.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.