Should we use URLs or refs in docstrings?

[TomAugspurger]

Discussion in #26497. Which do we prefer when linking from a docstring to the docs? Something like

ref:`categorical`

or

http://pandas.pydata.org/pandas-docs/stable/user_guide/categorical.html

[jreback]

we use ref's in our current sphinx output, so I think the ref's are fine (and more maintainable); downside of course is that you don't have the url from a terminal session, so +1 on the refs.

[WillAyd]

+1 on refs as well

[topper-123]

I'm +1 on urls; I like being able to copy/paste.

[TomAugspurger]

I think my preference is also for refs, because there less likely to be broken by section header renaming.

[jorisvandenbossche]

I think my preference depends on the situation: :ref:s for general interlinking to user guide pages, but using explicit urls for very specific links.

Example: the general link of "See the user guide for more details" (eg in rename, categorical note docstrings), I am fine with actual refs.
But for very specific links such as "for the allowed offset aliases, see here" (eg the allowed format strings in to_datetime or the allowed offset aliases in date_range (note here: the second link in "notes" is a full link, and actually not working any more ..)), I agree with @topper-123 that it is nice to actually be able to follow those links.

I think my preference is also for refs, because there less likely to be broken by section header renaming.

Section renaming should not have an impact, as long as we use labels for referencing (and don't change those labels lightly).
The main issue now that causes broken links is the moved pages. And that is something that (should) happens less often, and is not that much work to now fix all those cases.

[TomAugspurger]

Isn’t the HTML anchor link generated by the section title?

…

On May 27, 2019, at 03:03, Joris Van den Bossche ***@***.***> wrote: I think my preference depends on the situation: :ref:s for general interlinking to user guide pages, but using explicit urls for very specific links. Example: the general link of "See the user guide for more details" (eg in rename, categorical note docstrings), I am fine with actual refs. But for very specific links such as "for the allowed offset aliases, see here" (eg the allowed format strings in to_datetime or the allowed offset aliases in date_range (note here: the second link in "notes" is a full link, and actually not working any more ..)), I agree with @topper-123 that it is nice to actually be able to follow those links. I think my preference is also for refs, because there less likely to be broken by section header renaming. Section renaming should not have an impact, as long as we use labels for referencing (and don't change those labels lightly). The main issue now that causes broken links is the moved pages. And that is something that (should) happens less often, and is not that much work to now fix all those cases. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

[jorisvandenbossche]

Isn’t the HTML anchor link generated by the section title?

Yeah, it's true that I was mixing a bit sphinx labels for ref and actual html anchor links. But, they actually do work both. Eg

http://pandas-docs.github.io/pandas-docs-travis/user_guide/timeseries.html#offset-aliases
http://pandas-docs.github.io/pandas-docs-travis/user_guide/timeseries.html#timeseries-offset-aliases

both work. The first is based on the title (and is the default that you get if you click on the anchor next to the title on the actual page). The second one is based on the label and is what sphinx generates based on that label.

So if we would choose to use full urls in certain cases, we should ideally use the label-based urls and not title-based urls. So which would be an extra point of attention ..

[TomAugspurger]

Oh, I didn't realize both works. In that case, yes we should probably use the one generated by the .. _<ref>:, as that allows us to change the wording for people. Agreed that this is hard to enforce, but let's try to remember.

[TomAugspurger]

Using the URLs generated by the internal .. _<ref>: seems like a reasonable compromise.