Embed any block of content into the tooltip

[azhebel]

Now the tooltip includes everything in the doc or section that you specify. But what if you want some specific paragraph, or two, or a paragraph and a list, or whatever. It should be possible to mark up any content chunk with some kind of id and embed it into the tooltip.

[humitos]

I found how to do this. In fact, it can be done using just what we already have (without any code change) and using all the power of :ref: role from Sphinx.

The documentation linked, shows how to create manual labels immediately before a section and a figure to be able to reference to it. It also mentions that you can link to places that are not named (e.g. a regular paragraph, a list, code block, or any other thing). Using the later feature, we can embed any content that we want into the tooltip.

For example,

.. _first_paragraph:

This is the first paragraph of the whole section.

This one should not be included.

Another paragraph that should not be shown here.

.. _compound_section:

.. compound::

   This is a whole section that can be included in the tooltip.

   It contains multiple paragraphs, but also code examples:

   .. code-block:: python

      import datetime
      datetime.datetime.now()

   You can use **bold text** here as well.

   Even, include a table, or whatever you want:

   .. csv-table:: Frozen Delights!
      :header: "Treat", "Quantity", "Description"
      :widths: 15, 10, 30

      "Albatross", 2.99, "On a stick!"
      "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
      crunchy, now would it?"
      "Gannet Ripple", 1.99, "On a stick!"

With that content in one of our reStructuredText files, we can then refer to them like this to generate tooltips with specific content on them:

You can show a single paragraph as well, :hoverxref:`single paragraph tooltip <first_paragraph>`.

Note that only the first paragraph is included, even that there are more paragraph in the same section.

Include a :hoverxref:`whole compound text <compound_section>`.

Note that the whole .. compound:: directive is included which can contain nested directives as well.

With this trick you can include any chunk of content that you want in the tooltip.

The only limitation that this has, is that the content has to be rendered in a page, which maybe is not desirable because you want to show a specific summary of something in the tooltip that it's not anywhere else. In that case, you could create a specific page with the content of these kind of tooltips and mark it as :orphan: to not be included in any toctree.

It would be good to write a usage guide in our documentation for this "hidden feature".

[humitos]

One of the downsides that has the solution proposed in my previous comment is that the link of the tooltip will link to a page that just will have a bunch of tooltip content but it's not a real page for readers to read.

Another approach for this could be to create a new directive where you can define the content of the tooltip but also the target, like:

.. hoverxref::
	:target: section i

	This is the content of the tooltip to show when hover it.