Sphinx-Preview¶
Sphinx-Preview
shows small previews for selectable links in HTML documents.
Example:
Sphinx-Preview
is a Sphinx extension.It is maintained by danwos
And it may be helpful to get quick previews, e.g. of Sphinx-Needs objects
Sphinx-Preview
does not provide any rst directives or roles, as it detects automatically all links via
JavaScript.
But there is a bunch of configuration options to control behavior and style.
Warning
This project is in beta-phase. Support for Firefox seems to work well. Chromium based browsers have some problems with some specific pages in iframes (jumping page, no navigation to given anchor).
Showcase¶
Test yourself here: Needs Examples.
iframe handling¶
The iframe preview gets opened by mouseover and/or by clicking the icon (if icon_click = True
).
It gets closed, if the mouse leaves the link/icon. And it also gets closed, if the mouse leaves the iframe.
So as long as the mouse stays on the link/icon, the iframe window is open.
If you want to navigate inside the iframe, you should use icon_click = True
.
In this case the mouse can leave the icon and the iframe stays open.
Another click on the icon will close the iframe, or if the mouse leaves the iframe (after entering it once).
iframe position is also not fix. If the iframe window will be outside the current browser screen, the position and maybe size are recalculated, so that it fits on the screen.
Please take also into account, that mobile devices do not have a mouse. For them icon_click = True
is the best
configuration to let them open the preview window.
Configuration¶
Sphinx-Preview
provides a single configuration option, called preview_config
.
This must get a Python dictionary:
# conf.py
preview_config = {
"selector": "div.body a",
"not_selector": "div.needs_head a, h1 a, h2 a",
"set_icon": True,
"icon_only": True,
"icon_click": False,
"icon": " 👁",
"width": 500,
"height": 400,
"offset": {
"left": 20,
"top": 20
},
"timeout": 500,
}
selector / not_selector¶
Takes a jQuery selector to define which links shall be taken into account.
selector
cares about all found elements. And not_selector
defines, which links shall not be handled.
The internal javascript call looks like this:
$(config.selector).not(config.not_selector).each(function () {
// some internal voodoo
})
So selector
can be used to select all links inside the main container, e.g. div.body
, and
not_selector
may be used to remove all links inside h1
or h2
.
Default values:
- selector
div.body a
- not_selector
h1 a, h2 a, h3 a, h4 a, h5 a, div.needs_head a
Examples¶
div.body a.reference.internal
set_icon¶
If set_icon
is True
, an icon will be added at the end of the link.
Default: True
icon_only¶
If True
, only the icon will open the preview.
The link itself stays “normal” and will not open a preview window.
Default: True
icon_click¶
The icon behaves like a button:
click, preview window gets opened
click, preview window is closed.
No more mouseover affects for the icon.
Best solution, if preview window shall be used also on mobile devices.
Default: False
icon¶
Defines the icon or better a string.
Use Utf-8 icons to get some nice “images”.
Default: 👁
width¶
Width of the preview window in px.
Default: 500
height¶
Height of the preview window in px.
Default: 300
offset¶
Takes a dictionary with the keys left
and top
.
Both values define in px
the location of the preview window, relative to the starting position of the link.
Default:
{
'left': 20,
'top': 20
}
timeout¶
A time in ms
, after which the preview window gets shown.
Default: 250
.