Links in docstrings are broken

[weaverba137]

Consider this docstring:

class SDSSMuNu(ac.BaseCoordinateFrame):
    """SDSS Great Circle Coordinates

    Attributes
    ----------
    stripe
        SDSS `Stripe Number`_ .
    node
        Node of the great circle with respect to the celestial equator.
        In SDSS, this is almost always RA = 95.0 degrees.
    incl
        Inclination of the great circle with respect to the celestial
        equator.
    phi
        Counter-clockwise position angle w.r.t. north for an arc
        in the +nu direction.

    .. _`Stripe Number`: http://www.sdss.org/dr14/help/glossary/#stripe

    Parameters
    ----------
    mu : :class:`~astropy.coordinates.Angle`
        Angle corresponding to longitude measured along a stripe.
    nu : :class:`~astropy.coordinates.Angle`
        Angle corresponding to latitude measured perpendicular to a stripe.

    Notes
    -----
    http://www.sdss.org/dr12/algorithms/surveycoords/
    """

Using numpydoc v0.7, I get the following warning when building documentation:

[...]/pydl/pydlutils/coord.py:docstring of pydl.pydlutils.coord.SDSSMuNu:34: WARNING: Unknown target name: "stripe number".

As far as I can tell the link "Stripe Number" is perfectly valid reStructuredText.

[MSeifert04]

Could be related to #114.

[jnothman]

it's unrelated. The issue is that sections like attributes aren't parsed directly as ReST. so if you put the target definition in notes etc it should work. I agree this is a bit of an issue and numpydoc should pass through lines beginning ..

[weaverba137]

OK, in fact moving the target to a different section does seem to work:

class SDSSMuNu(ac.BaseCoordinateFrame):
    """SDSS Great Circle Coordinates

    Attributes
    ----------
    stripe
        SDSS `Stripe Number`_ .
    node
        Node of the great circle with respect to the celestial equator.
        In SDSS, this is almost always RA = 95.0 degrees.
    incl
        Inclination of the great circle with respect to the celestial
        equator.
    phi
        Counter-clockwise position angle w.r.t. north for an arc
        in the +nu direction.

    Parameters
    ----------
    mu : :class:`~astropy.coordinates.Angle`
        Angle corresponding to longitude measured along a stripe.
    nu : :class:`~astropy.coordinates.Angle`
        Angle corresponding to latitude measured perpendicular to a stripe.

    Notes
    -----
    http://www.sdss.org/dr12/algorithms/surveycoords/

    .. _`Stripe Number`: http://www.sdss.org/dr14/help/glossary/#stripe
    """

This is a good enough workaround for me to keep working, but this could trip up lots of people, and still should be fixed.

[jnothman]

it's not so easy to fix elegantly for all cases...

[weaverba137]

OK, fair enough, but it should be easy to document this as a known issue at least.

[stefanv]

Good point; I think we answer enough numpydoc installation, configuration, and usage issues that some Sphinx documentation is warranted. With the added benefit that we can use numpydoc inside that sphinx build, to give some more examples, and to ensure that we don't break in future Sphinx versions.

[jnothman]

Btw, you could have also put the link definition within the description of stripe. The problem is formatting it in a way that numpydoc then parses it as an attribute/parameter/returnvalue name.

We now have docs local to the repository. Please feel free to submit a PR modifying https://github.com/numpy/numpydoc/blob/master/doc/format.rst