1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
Welcome to sphinx-hoverxref!
============================
``sphinx-hoverxref`` is a :doc:`Sphinx <sphinx:index>` extension to show a floating window (*tooltips* or *modal* dialogues) on the cross references of the documentation embedding the content of the linked section on them. With ``sphinx-hoverxref``, you don't need to click a link to see what's in there.
.. figure:: poliastro-usage.gif
:align: center
Example using ``sphinx-hoverxref`` in `poliastro <https://docs.poliastro.space/>`_
Usage
-----
To show a floating window, use the role ``hoverxref`` to link to any document or section and embed its content into it.
We currently support two different types of floating windows: Tooltip and Modal.
.. tabs::
.. tab:: Default
Writing this reStructuredText in your document:
.. code-block:: rst
This will :hoverxref:`show a floating window <hoverxref:hoverxref>` in the linked words.
it will be rendered to:
This will :hoverxref:`show a floating window <hoverxref:hoverxref>` in the linked words.
.. note::
The default style (tooltip or modal) is defined by the config :confval:`hoverxref_role_types <hoverxref_role_types>`.
.. tab:: Tooltip style
To *force* the floating window to be a tooltip, you can use ``:hoverxreftooltip:`` role instead.
.. code-block:: rst
This will :hoverxreftooltip:`show a tooltip <hoverxref:hoverxref>` in the linked words.
it will be rendered to:
This will :hoverxreftooltip:`show a tooltip <hoverxref:hoverxref>` in the linked words.
.. tab:: Modal style
To *force* the floating window to be a modal, you can use ``:hoverxrefmodal:`` role instead.
.. code-block:: rst
This will :hoverxrefmodal:`show a modal <hoverxref:hoverxref>` in the linked words.
it will be rendered to:
This will :hoverxrefmodal:`show a modal <hoverxref:hoverxref>` in the linked words.
.. tip::
These new roles are alias of the ``ref`` role and works in the same.
See :ref:`usage:usage` for more detailed information about this and other examples.
----
Reference
---------
Online documentation:
https://sphinx-hoverxref.readthedocs.io/
Source code repository (and issue tracker):
https://github.com/readthedocs/sphinx-hoverxref/
Badges:
|Build| |PyPI version| |Docs badge| |License|
.. toctree::
:maxdepth: 2
:caption: Contents
installation
usage
configuration
who-is-using-it
development
releasing
.. toctree::
:maxdepth: 2
:caption: API Reference
autoapi/hoverxref/index
.. _Read the Docs: https://readthedocs.org
.. |Build| image:: https://circleci.com/gh/readthedocs/sphinx-hoverxref.svg?style=svg
:target: https://circleci.com/gh/readthedocs/sphinx-hoverxref
:alt: Build status
.. |PyPI version| image:: https://img.shields.io/pypi/v/sphinx-hoverxref.svg
:target: https://pypi.org/project/sphinx-hoverxref
:alt: Current PyPI version
.. |Docs badge| image:: https://readthedocs.org/projects/sphinx-hoverxref/badge/?version=latest
:target: https://sphinx-hoverxref.readthedocs.io/en/latest/?badge=latest
:alt: Documentation status
.. |License| image:: https://img.shields.io/github/license/readthedocs/sphinx-hoverxref.svg
:target: LICENSE
:alt: Repository license
|
