Fix global CONTRIBUTING link

[strugee]

Fixes the live contributing guidelines link, which just links to https://flask.palletsprojects.com/en/stable/contributing/_contrib (i.e. it puts the RST slug in the URL somehow).

I wrapped to 80 characters, let me know if that's incorrect.

[davidism]

Please fix this using the named link syntax, inline links on large phrases are too hard to read/edit later.

[strugee]

Will try - I looked at the reStructuredText reference while I was writing the patch earlier and couldn't understand how to actually do this. Happy to look again/harder though.

[strugee]

@davidism fixed!

[davidism]

Sorry, I didn't communicate what I was looking for well. I want you to fix the existing syntax, not change to inline or to a full reference. I want to keep the short reference name.

[davidism]

I think it might be switching from <_contrib> to <contrib_>? It looks like that in a few other places in the docs.

[strugee]

Ohhh, I didn't realize there were other references - not super familiar with rST. Will grep when I'm back in the sprints room!

[strugee]

Or feel free to just fix the patch yourself/do it yourself on the off chance it's causing confusion in the Pallets sprint room

[strugee]

@davidism should finally be what you want, thanks for working with me!

[gmilde]

@strugee @davidism

Please fix this using the named link syntax, inline links on large phrases are too hard to read/edit later.

IMO, in this use case the anonymous link syntax is best suited:

See the Pallets `detailed contributing documentation`__ for many ways
to contribute, including reporting issues, requesting features, asking or
answering questions, and making PRs.

__ https://palletsprojects.com/contributing/

The named hyperlink syntax makes only sense, if you want to (re-)use the reference name in a simple link somewhere else.

[davidism]

I don't understand anonymous links, their documentation is lacking. How does this work if there are multiple links on a page? Also, occasionally we do reference the same link multiple times, so defaulting to that style makes more sense to me.

[gmilde]

I don't understand anonymous links, their documentation is lacking. How does this work if there are multiple links on a page?

Anonymous hyperlinks are documented in the reStructuredText Markup Specification.
Similar to auto-numbered footnotes, they match by their position, e.g.

__ https://example.org/link-1.html

Text with link-1__, link-2__, and link-3__.

__ contrib_
__ the-file-linked-to-by-link-3.txt

Also, occasionally we do reference the same link multiple times, so defaulting to that style makes more sense to me.

You are right, if you re-use the "reference names" or prefer a large "target section" at the end of the document, "labeled" links are better suited.

Mark, however, the difference between

`detailed contributing documentation <contrib_>`_

and

`detailed contributing documentation <contrib_>`__

The first variant (with only one trailing underscore at the very end) registers the link text as "reference name" (label). This allows subsequent references to the same target without embedded alias like See the `detailed contributing documentation`_ for more info..

The second variant (with two trailing underscores) allows using the same link text for different links

For details, see `here <contrib_>`__ and `here <policy_>`__.

[davidism]

That's good to know, rST links are a lot more complicated than I already thought they were. Ultimately, we're moving to myst-parser and Markdown, so this problem will go away.

[gmilde]

That's good to know, rST links are a lot more complicated than I already thought they were. Ultimately, we're moving to myst-parser and Markdown, so this problem will go away.

IMV, the CommonMark Spec on hyperlinks is not less complicated than the corresponding reStructuredText Markup Specification. The problem is the misleading Sphinx rST primer.

Looking at the concrete use case, a rST source file with a single hyperlink with long link text, the best suited and really simple syntax is an anonymous link:

/flask/doc/contributing.rst:

Contributing
============

See the Pallets `detailed contributing documentation`__ for many ways
to contribute, including reporting issues, requesting features, asking or
answering questions, and making PRs.

__ https://palletsprojects.com/contributing/