Opened 4 years ago

Closed 10 months 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
(diff, github, buildbot, log)
Author: julian Launchpad Bug:

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 4 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 4 years ago by thijs

  • Cc thijs added

+1 for intersphinx.

comment:3 Changed 4 years ago by khorn

  • Milestone set to Lore to Sphinx

comment:4 Changed 4 years ago by khorn

  • Owner changed from glyph to khorn

comment:5 in reply to: ↑ 1 Changed 4 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 4 years ago by <automation>

  • Owner khorn deleted

comment:7 Changed 4 years ago by khorn

  • Milestone Lore to Sphinx deleted

This should not be part of the Lore to Sphinx milestone

comment:8 Changed 10 months ago by julian

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

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

comment:9 Changed 10 months 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 10 months ago by khorn

  • Owner set to khorn

comment:11 Changed 10 months 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 10 months ago by khorn

Forgot to mention, this probably also needs a topfile.

comment:13 Changed 10 months ago by Julian

  • Keywords review added
  • Owner changed from Julian to khorn

Thanks!

comment:14 Changed 10 months ago by khorn

  • Keywords review removed
  • Owner changed from khorn to Julian

Looks good. Please merge.

comment:15 Changed 10 months 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.