Use different colour for 'Return value: Borrowed reference'

[hugovk]

Follow on from python/cpython#117926.

Currently light green is used for all return types:

• "Return value: Always NULL."
• "Return value: New reference."
• "Return value: Borrowed reference."

For example: https://docs.python.org/3/c-api/exceptions.html

A borrowed reference is not necessarily a "bad" thing, but we may want to use something other than green that indicates it's "good", to indicate they should be treated with care.

This PR uses the same yellow/orange colour as the "Changed in version x.y" text in #185 - I've already checked the contrast ratios in that PR and both meet WCAG AAA. By using the same colour, it will be easier to check/change when we audit.

For example: https://python-docs-theme-previews--188.org.readthedocs.build/en/188/c-api/exceptions.html#querying-the-error-indicator

[vstinner]

This PR uses the same yellow/orange colour as the "Changed in version x.y" text in #185

FYI As a color blind person, I don't see the difference between "Borrowed reference" and "New reference" colors in the light mode. Well, I'm also color blind, so my opinion may not matter :-)

In the dark mode, I see clearly that the two colors are very different.

[flying-sheep]

If you’re reusing existing colors, how about you centralize their definition as a CSS variables and then use it from both your new CSS rules and the old ones that originally defined the color?

[hugovk]

Good idea, shall we also replace the pale green for the other "Return value" with the "New in version" green?

The light mode ones are much closer, but we could replace one with the other here too?

[hugovk]

Updated:

Suggestions for better variable names welcome :)

[erlend-aasland]

I don't have a strong opinion regarding naming, but I like the change! Personally, I would prefer borrowed references to be labelled as "bad", but that is a different discussion.

[hugovk]

This is now deployed: https://docs.python.org/3/c-api/exceptions.html