add role for custom hyperlinks

[2bndy5]

Currently, setting the docutils.nodes.refernce class' reftitle attribute can only be used via docutils API. Some extensions already use this attribute to add tooltips for hyperlinks, namely intersphinx and a bunch of extensions exclusive to this theme.

The rST specs do not allow doc authors to specify custom hyperlink tooltips. This is actually pretty standard in markdown:

[link text](https://example.com "tooltip text")

renders as link text

It shouldn't be too hard to implement this as a sphinx extension. I'm imagining a href role that behaves similarly to ref role with this added behavior.

proposed syntax

.. with link text
:href:`link text <link_url "tooltip text">`

.. without link text (where link_url becomes the link text)
:href:`<link_url "tooltip text">`

It would be nice to actually derive from the ref role and just add some extra content parsing where appropriate.

---

PS - marking this as a comparable upstream feature because mkdocs-material release "improved toolips" support in v9.5.0

[2bndy5]

I think it would also be cool if we could allow custom CSS class(es) to create buttons.

:href:`link text <link_url "tooltip text">;md-button`

Although, a case could be made that a derivative of our si-icon would be more useful to embed inline icons with text in a hyperlink. I'm not sure how this syntax would look since rST doesn't support nested syntax (& substitutions are limited in that roles cannot be used as substitutions' values). Maybe something like

:si-href:`link text {material/logo} <link_url "tooltip text">;custom-class`

---

Using rst-class treats a rogue hyperlink as a paragraph:

.. rst-class:: md-button md-button-primary

`Subscribe to our newsletter <#>`_

renders as the following HTML:

<p class="md-button md-button-primary">
  <a class="reference external" href="#">Subscribe to our newsletter</a>
</p>