Add floating window tooltips for cross-references in the docs

docs/conf.py

@@ -56,6 +56,7 @@
     "nbsphinx",
     "IPython.sphinxext.ipython_console_highlighting",
     "sphinx_gallery.load_style",
+    "hoverxref.extension",
 ]
 
 # -- sphinxcontrib-bibtex configuration --------------------------------------
@@ -301,6 +302,31 @@
 
 """
 
+# -- Options for sphinx-hoverxref --------------------------------------------
+
+# Hoverxref settings
+
+hoverxref_default_type = "tooltip"
+hoverxref_auto_ref = True
+
+hoverxref_roles = ["class", "meth", "func", "ref", "term"]
+hoverxref_role_types = dict.fromkeys(hoverxref_roles, "tooltip")
+
+hoverxref_domains = ["py"]
+
+# Currently, only projects that are hosted on readthedocs + CPython, NumPy, and
+# SymPy are supported
+hoverxref_intersphinx = list(intersphinx_mapping.keys())
+
+# Tooltips settings
+hoverxref_tooltip_lazy = False
+hoverxref_tooltip_maxwidth = 750
+hoverxref_tooltip_animation = "fade"
+hoverxref_tooltip_animation_duration = 1
+hoverxref_tooltip_content = "Loading information..."
+hoverxref_tooltip_theme = ["tooltipster-shadow", "tooltipster-shadow-custom"]
+
+
 # -- Jinja templating --------------------------------------------------------
 # Credit to: https://ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/
 

docs/requirements.txt

@@ -29,3 +29,4 @@ ipython
 ipykernel
 ipywidgets
 sphinx-gallery
+sphinx-hoverxref

docs/source/_static/pybamm.css

@@ -144,3 +144,26 @@ html[data-theme="dark"] h1 {
 html[data-theme="dark"] h3 {
   color: #0a6774;
 }
+
+/* Overrides for sphinx-hoverxref since it does not support a native dark theme, see */
+/* https://github.com/readthedocs/sphinx-hoverxref/issues/231 */
+
+/* These will ensure that the tooltip inherits the PyData colours */
+
+.tooltipster-sidetip.tooltipster-shadow .tooltipster-box {
+  background: var(--pst-color-background) !important;
+}
+
+.tooltipster-sidetip.tooltipster-shadow .tooltipster-arrow {
+  background: none !important;
+  overflow: hidden;
+  position: absolute;
+}
+
+.tooltipster-sidetip.tooltipster-shadow.tooltipster-right .tooltipster-arrow-border {
+  border-right-color: var(--pst-color-background) !important;
+}
+
+.tooltipster-sidetip.tooltipster-shadow.tooltipster-left .tooltipster-arrow-border {
+  border-left-color: var(--pst-color-background) !important;
+}

docs/source/user_guide/index.md

@@ -1,4 +1,4 @@
-(user)=
+(user_guide)=
 
 # PyBaMM user guide
 

setup.py

@@ -236,6 +236,7 @@ def compile_KLU():
             "ipykernel",
             "ipywidgets",
             "sphinx-gallery",
+            "sphinx-hoverxref",
         ],  # For doc generation
         "dev": [
             "pre-commit",  # For code style checking