Rich hover over tips

Rich hover over tips#

This page reuses MIT licensed content from TeachBooks (2024). Find out more here.

User types

This page is useful for user type 3, 4 and 5.

Sphinx Extension

Introduction#

Sphinx-tippy allows you to create rich hover over tips as demonstrated here: https://sphinx-tippy.readthedocs.io/en/latest/. This TeachBooks Tippy extension makes it plug-and-play within a TeachBook.

The differences with Sphinx-tippy are:

  • Default inclusion of useful CSS-file.

  • Default activation of sphinx.ext.mathjax.

  • Default loading method of defer changed to None for supporting JavaScript.

  • Default support for TeachBooks Sphinx Grasple such that images are shown (as iframes are not loaded).

  • Limit the showing of tool tips to the <main> anchor of the Sphinx book.

  • Limit the maximum height of a tool tip.

  • Force tool tips to remain with visible document body.

  • No arrow that points from the tool tip to the link.

What does it do?#

You can see how the this works in the example book.

Installation#

To install TeachBooks-Sphinx-Tippy, follow these steps:

Step 1: Install the Package

Install the teachbooks-sphinx-tippy package using pip:

pip install teachbooks-sphinx-tippy

Step 2: Add to requirements.txt

Make sure that the package is included in your project’s requirements.txt to track the dependency:

teachbooks-sphinx-tippy

Step 3: Enable in _config.yml

In your _config.yml file, add the extension to the list of Sphinx extra extensions (important: underscore, not dash this time):

sphinx: 
    extra_extensions:
        - teachbooks_sphinx_tippy

Usage#

By following the steps above, the extension will be added automatically.

Contribute#

This tool’s repository is stored on GitHub. The README.md of the branch Manual is also part of the TeachBooks manual as a submodule. If you’d like to contribute, you can create a fork and open a pull request on the GitHub repository. To update the README.md shown in the TeachBooks manual, create a fork and open a merge request for the GitHub repository of the manual. If you intent to clone the manual including its submodules, clone using: git clone --recurse-submodulesgit@github.com:TeachBooks/manual.git.

Contents