From 19f9b59e58d3d8bddae39d1f290b5b6e7e9fee19 Mon Sep 17 00:00:00 2001
From: arl <me@arielle.codes>
Date: Tue, 25 Oct 2022 11:28:51 -0400
Subject: [PATCH] docs: show hoverxref for intersphinx projects (#788)

shows hoverxref on stdlib objects and aiohttp/requests documentation as
well.

Co-authored-by: shiftinv <me@shiftinv.cc>
---
 docs/conf.py                       | 22 ++++++++++++++++------
 docs/faq.rst                       |  4 ++--
 requirements/requirements_docs.txt |  2 +-
 3 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 99fc6f047d..8baf671c4b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -69,12 +69,6 @@
 
 extlinks_detect_hardcoded_links = True
 
-# Links used for cross-referencing stuff in other documentation
-intersphinx_mapping = {
-    "py": ("https://docs.python.org/3", None),
-    "aio": ("https://docs.aiohttp.org/en/stable/", None),
-    "req": ("https://requests.readthedocs.io/en/latest/", None),
-}
 
 rst_prolog = """
 .. |coro| replace:: This function is a |coroutine_link|_.
@@ -234,6 +228,22 @@ def linkcode_resolve(domain: str, info: Dict[str, Any]) -> Optional[str]:
 hoverxref_tooltip_theme = ["tooltipster-custom"]
 hoverxref_tooltip_lazy = True
 
+# these have to match the keys on intersphinx_mapping, and those projects must be hosted on read the docs.
+hoverxref_intersphinx = [
+    "py",
+    "aio",
+    "req",
+]
+
+# Links used for cross-referencing stuff in other documentation
+# when this is updated hoverxref_intersphinx also needs to be updated IF THE docs are hosted on readthedocs.
+intersphinx_mapping = {
+    "py": ("https://docs.python.org/3", None),
+    "aio": ("https://docs.aiohttp.org/en/stable/", None),
+    "req": ("https://requests.readthedocs.io/en/latest/", None),
+}
+
+
 # use proxied API endpoint on rtd to avoid CORS issues
 if os.environ.get("READTHEDOCS"):
     hoverxref_api_host = "/_"
diff --git a/docs/faq.rst b/docs/faq.rst
index c025a8b5a4..94975260df 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -55,8 +55,8 @@ instead. Similar to this example: ::
     # good
     await asyncio.sleep(10)
 
-Another common source of blocking for too long is using HTTP requests with the famous module :doc:`req:index`.
-While :doc:`req:index` is an amazing module for non-asynchronous programming, it is not a good choice for
+Another common source of blocking for too long is using HTTP requests with the famous module :doc:`requests <req:index>`.
+While :doc:`requests <req:index>` is an amazing module for non-asynchronous programming, it is not a good choice for
 :mod:`asyncio` because certain requests can block the event loop too long. Instead, use the :doc:`aiohttp <aio:index>` library which
 is installed on the side with this library.
 
diff --git a/requirements/requirements_docs.txt b/requirements/requirements_docs.txt
index 58f91f564a..a72dac9ea9 100644
--- a/requirements/requirements_docs.txt
+++ b/requirements/requirements_docs.txt
@@ -1,7 +1,7 @@
 docutils>=0.17
 sphinx==5.3.0
 sphinxcontrib-trio~=1.1.2
-sphinx-hoverxref==1.2.0
+sphinx-hoverxref==1.3.0
 sphinx-autobuild~=2021.3
 sphinxcontrib-towncrier==0.3.0a0
 towncrier==22.8.0