[IPython-dev] Link styles in documentation

[Thomas Kluyver]

It seems Sphinx lets us insert two distinct kinds of links: `link`_ puts the
link inline, while [link]_ points you to a footnote for the link (reST calls
this a citation), and we're using something of a mixture of the two. In
principle, reST should format `link`_ according to the output, so when we
generate a PDF, it should appear as a footnote (the 'call-out form'). It
seems Sphinx doesn't take advantage of this and leaves `link`_ inline for
the PDF output.

I suggest that we use `link`_ formatting consistently, and enable the sphinx
options latex_show_urls and latex_show_pagerefs. This will mean links are a
single click in our HTML output, and internal & external links can be read
in the printed PDF output (The URL or page reference appears in brackets
after the link).

Thomas
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20110903/a3ec0277/attachment.html>