informative adjunct to the docs. Forward-port of Raymond's r86225 and r86245 using the new source reST role added in #10334.