[IPython-dev] Link styles in documentation

[Fernando Perez]

On Sat, Sep 3, 2011 at 5:22 AM, Thomas Kluyver <takowl at gmail.com> wrote:
> 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).

+1

Feel free to update these at will as you encounter them without a PR;
from your recent (much welcome) summary it's obvious we need to
preserve our limited review resources for pure code, so be liberal
with doc updates.  We all trust each other and can clean up little
slip-ups later if need be.

Cheers,

f