Repository: PlasmaPy/PlasmaPy

Issue:
Fully define configuration values for sphinx-hoverxref in `docs/conf.py`
Previously we had added the [sphinx-hoverxref](https://sphinx-hoverxref.readthedocs.io/en/latest/index.html) extension, but we did not fully define the configuration variables that go into `docs/conf.py`.  The only one we defined so far was `hoverxref_auto_ref` which only affects the `:ref:` role. We still need to add in the relevant [sphinx-hoverxref configuration variables](https://sphinx-hoverxref.readthedocs.io/en/latest/configuration.html).


Discussion:
I forgot to mention something @rocco8773 had pointed out — there are also a lot of hoverxref warnings that show up in the documentation build (at least when using `make` locally and possibly with `tox` as well, I think).  If we set up the config variables, that _should_ also address the hoverxref warnings. 

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -107,12 +107,13 @@
 # in other packages. When mappings are removed or added, please update
 # the section in docs/doc_guide.rst on references to other packages.
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
+    "readthedocs": ("https://docs.readthedocs.io/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
     "astropy": ("https://docs.astropy.org/en/stable/", None),
-    "pytest": ("https://docs.pytest.org/en/stable", None),
+    "pytest": ("https://docs.pytest.org/en/stable/", None),
     "sphinx_automodapi": (
         "https://sphinx-automodapi.readthedocs.io/en/latest/",
         None,
@@ -120,6 +121,18 @@
     "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
     "numba": ("https://numba.readthedocs.io/en/stable/", None),
 }
+hoverxref_intersphinx = [
+    "readthedocs",
+    "python",
+    "numpy",
+    "scipy",
+    "pandas",
+    "astropy",
+    "pytest",
+    "sphinx_automodapi",
+    "sphinx",
+    "numba",
+]
 
 autoclass_content = "both"
 
@@ -213,7 +226,48 @@
 # Use a code highlighting style that meets the WCAG AA contrast standard
 pygments_style = "default"
 
+# adapted from sphinx-hoverxref conf.py
+if os.environ.get("READTHEDOCS"):
+    # Building on Read the Docs
+    hoverxref_api_host = "https://readthedocs.org"
+
+    if os.environ.get("PROXIED_API_ENDPOINT"):
+        # Use the proxied API endpoint
+        # - A RTD thing to avoid a CSRF block when docs are using a
+        #   custom domain
+        hoverxref_api_host = "/_"
+
+hoverxref_tooltip_maxwidth = 600  # RTD main window is 696px
 hoverxref_auto_ref = True
+hoverxref_mathjax = True
+hoverxref_sphinxtabs = True
+
+# hoverxref has to be applied to these
+hoverxref_domains = ["py", "cite"]
+hoverxref_roles = ["confval", "term"]
+
+hoverxref_role_types = {
+    # roles with cite domain
+    "p": "tooltip",
+    "t": "tooltip",
+    #
+    # roles with py domain
+    "attr": "tooltip",
+    "class": "tooltip",
+    "const": "tooltip",
+    "data": "tooltip",
+    "exc": "tooltip",
+    "func": "tooltip",
+    "meth": "tooltip",
+    "mod": "tooltip",
+    "obj": "tooltip",
+    #
+    # roles with std domain
+    "confval": "tooltip",
+    "hoverxref": "tooltip",
+    "ref": "tooltip",
+    "term": "tooltip",
+}
 
 # -- Options for HTML output ----------------------------------------------
 


Test patch: