Opened 6 years ago

Closed 3 years ago

#4582 enhancement closed fixed (fixed)

Twisted's Sphinx documentation should allow linking to stdlib documentation.

Reported by: Screwtape Owned by: Julian
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: khorn, thijs Branch: branches/intersphinx-4582
branch-diff, diff-cov, branch-cov, buildbot
Author: julian

Description

In ticket #4567 comment 4, exarkun writes:

I suppose eventually we can have a stdlib module role which is both fixed-width like code and a link. Does that make sense? Can you file a ticket for this?

I don't know of any other Python projects whose docs link to the Python stdlib docs (especially since I don't think the Python stdlib has any version-independent permalinks), but it would be a nice feature.

Change History (15)

comment:1 follow-up: Changed 6 years ago by khorn

This can be done one of two ways:

  1. Since the python stdlib docs use Sphinx, we can use Intersphinx, which allows links between Sphinx projects. This has the advantage that it's a built-in Sphinx feature with no additional code to maintain.
  2. Create a custom extension with a stdlib role or something as exarkun suggested. This would allow a bit more flexibility than the Intersphinx option as far as formatting, etc.

comment:2 Changed 6 years ago by thijs

  • Cc thijs added

+1 for intersphinx.

comment:3 Changed 6 years ago by khorn

  • Milestone set to Lore to Sphinx

comment:4 Changed 6 years ago by khorn

  • Owner changed from glyph to khorn

comment:5 in reply to: ↑ 1 Changed 6 years ago by thijs

Replying to khorn:

This can be done one of two ways:

  1. Since the python stdlib docs use Sphinx, we can use Intersphinx, which allows links between Sphinx projects. This has the advantage that it's a built-in Sphinx feature with no additional code to maintain.

With InterSphinx you can use syntax like:

:py:mod:`urllib2`

in conf.py:

# refer to the Python standard library.
intersphinx_mapping = {'python': ('http://docs.python.org', None)}

comment:6 Changed 5 years ago by <automation>

  • Owner khorn deleted

comment:7 Changed 5 years ago by khorn

  • Milestone Lore to Sphinx deleted

This should not be part of the Lore to Sphinx milestone

comment:8 Changed 3 years ago by julian

  • Author set to julian
  • Branch set to branches/intersphinx-4582

(In [41287]) Branching to intersphinx-4582.

comment:9 Changed 3 years ago by Julian

  • Keywords review added

Here's a branch with the 5 lines to get this hooked up.

I've added two intersphinx sources, one for py2 and one for py3 -- intersphinx allows you to be explicit if we want to link to one or the other in places where it matters, otherwise it will just detect which one it needs to look at for unmabiguous refs.

If this is agreeable, I'll add a note somewhere on which prefixes we've got.

comment:10 Changed 3 years ago by khorn

  • Owner set to khorn

comment:11 Changed 3 years ago by khorn

  • Keywords review removed
  • Owner changed from khorn to Julian

Review notes:

  1. A note on which prefixes are set up, as you mentioned, would be nice.
  2. You didn't say anything about intersphinx_cache_limit. I see no particular reason to change it from the default (5 days), but you might put a comment in the conf.py file so that it's obvious that this was a conscious decision, and not an oversight.

Don't block on the above though. Please merge when ready.

comment:12 Changed 3 years ago by khorn

Forgot to mention, this probably also needs a topfile.

comment:13 Changed 3 years ago by Julian

  • Keywords review added
  • Owner changed from Julian to khorn

Thanks!

comment:14 Changed 3 years ago by khorn

  • Keywords review removed
  • Owner changed from khorn to Julian

Looks good. Please merge.

comment:15 Changed 3 years ago by julian

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

(In [41312]) Merge intersphinx-4582: Add support for intersphinx links to stdlib docs.

Author: Julian Reviewers: khorn Fixes: #4582

Adds py2 and py3 prefixes for the two corresponding stdlib documentation indices.

Note: See TracTickets for help on using tickets.