📚 DOCS: Add the sphinx-tippy extension (#684)

Author: chrisjsewell

.readthedocs.yml

@@ -1,7 +1,7 @@
 version: 2
 
 python:
-  version: "3"
+  version: "3.8"
   install:
       - method: pip
         path: .

docs/_static/local.css

@@ -1,16 +1,16 @@
 /** Add a counter before subsections **/
-h1 {
+h1:not(.tippy-header) {
     counter-reset: subsection;
     text-decoration: underline;
 }
-h2 {
+h2:not(.tippy-header) {
     counter-reset: subsubsection;
 }
-h2::before {
+h2:not(.tippy-header)::before {
     counter-increment: subsection;
     content: counter(subsection) ". ";
 }
-h3::before {
+h3:not(.tippy-header)::before {
     counter-increment: subsubsection;
     content: counter(subsection) "." counter(subsubsection) ". ";
 }

docs/conf.py

@@ -36,6 +36,7 @@
     "sphinxcontrib.mermaid",
     "sphinxext.opengraph",
     "sphinx_pyscript",
+    "sphinx_tippy",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -149,6 +150,18 @@
     "explain/index.md": "develop/background.md",
 }
 
+tippy_skip_anchor_classes = ("headerlink", "sd-stretched-link", "sd-rounded-pill")
+tippy_anchor_parent_selector = "article.bd-article"
+tippy_custom_tips = {
+    "https://www.sphinx-doc.org/en/master/usage/configuration.html": """
+<p>The configuration directory must contain a file named
+<code class="file docutils literal notranslate"><span class="pre">conf.py</span></code>.
+This file (containing Python code) is called the “build configuration file”
+and contains (almost) all configuration needed to customize Sphinx input
+and output behavior.</p>
+    """
+}
+
 # -- LaTeX output -------------------------------------------------
 
 latex_engine = "xelatex"

docs/syntax/optional.md

@@ -21,7 +21,7 @@ myst:
 # Syntax Extensions
 
 MyST-Parser is highly configurable, utilising the inherent "plugability" of the [markdown-it-py](inv:markdown_it#index) parser.
-The following syntaxes are optional (disabled by default) and can be enabled *via* the sphinx `conf.py` (see also [](sphinx/config-options)).
+The following syntaxes are optional (disabled by default) and can be enabled *via* the {{ confpy }} (see also [](sphinx/config-options)).
 Their goal is generally to add more *Markdown friendly* syntaxes; often enabling and rendering [markdown-it-py plugins](inv:markdown_it#md/plugins) that extend the [CommonMark specification](https://commonmark.org/).
 
 To enable all the syntaxes explained below:

pyproject.toml

@@ -61,6 +61,7 @@ rtd = [
     "sphinxcontrib.mermaid~=0.7.1",
     "sphinxext-opengraph~=0.7.5",
     "sphinx-pyscript",
+    "sphinx-tippy>=0.3.1",
 ]
 testing = [
     "beautifulsoup4",