Docs: enable tooltips on documentation

[humitos]

Summary of changes

I'm suggesting installing the Sphinx extension sphinx-hoverxref to enable tooltips when hovering internal and external references (via intersphinx).

I set up a testing project on Read the Docs to show what it looks like in a live preview. Check it out at https://humitos-setuptools.readthedocs.io/en/docs-tooltips/userguide/quickstart.html

Let me know if this is something you like and if you want me to do any changes for the PR to be approved.

Quick Examples

Here is a small GIF showing it in action and internal reference.

Another GIF showing an external reference pointing to twine:

---

Pull Request Checklist

• Changes have tests
• News fragment added in changelog.d/.
  (See documentation for details)

[abravalheri]

Hi @humitos, thank you very much. I think this looks great (and it would be a nice improvement in UX for the docs).

I have one question about the implementation. Do you believe that pinning the dependency to a fixed release is the best way to go? I understand that it makes things easier and more reproducible, but it will also mean that we don't get automatic security updates/bug fixes, right? (The same comment would be valid for the other PR).

[humitos]

Hi @abravalheri! Wow, that reply was fast! I think that's a preference for the maintainers of each project. I usually prefer to pin my dependencies to have more control of them and run periodic updates with pip-tools or similar.

I wasn't sure what pattern to follow here since there are dependencies that are pinned and some others that are not in the setup.cfg file, so I pinned following my personal preference 😄 . I'm happy to unpin it if you prefer, tho.

[abravalheri]

Thank you very much for the clarification Manuel.

I noticed that you are one of the maintainers in both extensions, so maybe you would know if they follow something vaguely similar to semver... If they do, maybe it would make sense to use something like a compatible release version operator (~=) or a >=X.Y,<X+1 to implement a next major cap¹.

Setuptools currently does not have a automatic periodic dependency check, so chances are that these versions will end-up frozen until we notice some incompatibility 😅.

Footnotes

1. Although sphinx-notfound-page does not seem to have reached 1.0 yet, so it might make sense to pin to protect against incompatible changes. ↩

[humitos]

I'm one of the maintainers in both extensions, yes. They have been working pretty nice and are quite stable at the moment. We are not expecting major changes in the near future, and we are following the development of Sphinx closely to avoid any incompatibility that we can anticipate.

We do follow semver versioning in both of them, so I'm happy to use sphinx-hoverxref<2 and sphinx-notfound-page==0.8.3 until it gets 1.0. I'll push a commit with the updates on this PR.

[abravalheri]

Thank you very much @humitos. I will leave these 2 PRs open for a little bit to see if the other maintainers have any objection, but it looks great to me!

I had a look on the docs for sphinx-hoverxref, and I have a doubt (just for future reference). Could we, for example use something like the following in the configuration:

hoverxref_roles = [
    'doc',
    'pep',
    'term',
]

i.e., does it mean that we can apply the hover to any role?

[humitos]

@abravalheri yes, you can apply hoverxref on specific roles by defining hoverxref_roles as you did, or setting hoverxref_auto_ref = True to apply them in all the possible references --which is what I've done in this PR. So, every Sphinx role that is supported on sphinx-hoverxref should currently show a tooltip in the documentation.

If with the current configuration you notice there are roles where you would like to see a tooltip but it does not work, please let me know or open an issue on https://github.com/readthedocs/sphinx-hoverxref and I will check it out. Maybe it's a bug, maybe it's just not yet supported, or maybe is just a miss configuration 😄

BTW, we've touched on the doc role in readthedocs/sphinx-hoverxref#18

[humitos]

Hi! I just wanted to check if you all are happy with this PR or if you want me to make any change before merging.

[abravalheri]

Hi @humitos, sorry for the delay, this PR slipped under my radar.

I think this PR should be fine as it is now right? If we notice some problems we will open an issue on the plugin tracker :)

Thank you very much for the contribution.

[humitos]

That's great! I'm happy you found it useful. I'd appreciate any feedback you may have 💪🏼 and/or bugs 🐞