Add a Sphinx role to link to GitHub labels

[hugovk]

This adds a :gh-label: role to link to a GitHub label on https://github.com/python/cpython.

For example:

• `:gh-label:`docs` -> https://github.com/python/cpython/issues?q=is%3Aopen+sort%3Aupdated-desc+label%3Adocs

• :gh-label:`skip news` -> https://github.com/python/cpython/issues?q=is%3Aopen+sort%3Aupdated-desc+label%3A%22skip+news%22

This makes it easy to click through to see recent examples of the actual label in use.

It also helps https://github.com/python/devguide/issues/821 because we can click through and find which labels have since been deleted (e.g. invalid) or renamed (library).

[ezio-melotti]

This makes it easy to click through to see recent examples of the actual label in use.

This might also be helpful in a couple of other places in the devguide that link e.g. to doc or easy issues, but I wonder if it's a bit overkill to create a role just for it 🤔

It also helps #821 because we can click through and find which labels have since been deleted (e.g. invalid) or renamed (library).

This will only work by clicking through the links manually, right? Even invalid labels will return a valid search page with no results, so we won't be able to detect them automatically. Also, FWIW, I'm fixing that section in #930.

[hugovk]

This might also be helpful in a couple of other places in the devguide that link e.g. to doc or easy issues, but I wonder if it's a bit overkill to create a role just for it 🤔

My thinking behind creating a role was that we can define all the params stuff in a single place, and it'll then also be consistent. Using GitHub's defaults here:

https://github.com/python/cpython/issues?q=is%3Aopen+sort%3Aupdated-desc+label%3Afoo

It also deals with escaping and quoting labels that contains spaces.

---

This will only work by clicking through the links manually, right?

Yep.

Even invalid labels will return a valid search page with no results, so we won't be able to detect them automatically.

Correct, just for manual checking.

Also, FWIW, I'm fixing that section in #930.

Great, I knew you were working on it somewhere, thank you!

[terryjreedy]

Any particular reason to sort by last update rather than the default of opening time? I don't know if it makes any difference on the load on GH. docs takes several seconds to return about 1200. Seems like overkill for examples.

[hugovk]

I used the default options GitHub gave me after clicking one of the labels in the issue list, at https://github.com/python/devguide/issues

Here's timings in a fresh Incognito window with local cache disabled, 3 loads for each.

The URLs used in this PR:

• https://github.com/python/cpython/issues?q=is%3Aopen+sort%3Aupdated-desc+label%3Adocs
• 5.81s
• 6.25s
• 6.55s
• Average: 6.20s

The same but removing the sort%3Aupdated-desc parameter:

• https://github.com/python/cpython/issues?q=is%3Aopen+label%3Adocs
• Resolved to https://github.com/python/cpython/labels/docs in the URL bar
• 4.71s
• 8.03s
• 5.98s
• Average: 6.24s

About the same?

But perhaps using the https://github.com/python/cpython/labels/docs form is the neatest?

[erlend-aasland]

But perhaps using the https://github.com/python/cpython/labels/docs form is the neatest?

Definitely; I'd go for that.

[hugovk]

Updated!

[ezio-melotti]

This might also be helpful in a couple of other places in the devguide that link e.g. to doc or easy issues

I searched through the devguide and I can confirm these are the only two places where they are currently used, but they link to issues only so we might not be able to use the new role if it links to https://github.com/python/cpython/labels/{LABEL-NAME}: https://github.com/python/devguide/blob/e807042f9b513092840d9acf1d8a0ffb7c9f3e05/documentation/help-documenting.rst#L66 https://github.com/python/devguide/blob/e807042f9b513092840d9acf1d8a0ffb7c9f3e05/getting-started/fixing-issues.rst#L25

In #930 I can add links to all the labels (the currently proposed link would work fine there), and I was also planning to add a page with several useful search queries (there it won't work). In addition in #930 I have another link that won't be able to use the role: https://github.com/python/cpython/labels?q=expert.

IOW, it looks like this role will be only useful in the page that lists the label, unless we make it more flexible.

[hugovk]

Yep, that's right.

Originally this PR used ugly links like https://github.com/python/cpython/issues?q=is%3Aopen+sort%3Aupdated-desc+label%3Adocs, but now has nicer ones like https://github.com/python/cpython/labels/docs

So it's less useful than before, but I think it's more readable to see :gh-label:docs` than a long link.

But I'm happy to close this, or replace with normal links, or wait for normal links in #930 :)