sphinxcontrib-images¶
sphinxcontrib-images (formerly sphinxcontrib-fancybox).
How to install?¶
pip install sphinxcontrib-images
Add extension to conf.py
in your sphinx project.
extensions = [
…
'sphinxcontrib.images',
…
]
How to configure?¶
You can configure behaviour by dictionary with options placed in conf.py
:
images_config = {
…
}
All available options with comments:
backend: | (default: ‘LightBox2’)
If If callable it can be a function or a class which returns instance of a backend to render images. First argument is Sphinx’s app instance. Go to LightBox2 backend to see how to implement that. |
---|---|
override_image_directive: | |
(default:
|
|
cache_path: | (default : Path, where to keep downloaded images. Relative to
source (actually relative to |
requests_kwargs: | |
(default: Remote images are downloaded by requests. This
|
|
default_image_width: | |
(default: Default width of an image. Backend can use this setting do set width properly. |
|
default_image_height: | |
(default: Default height of an image. Backend can use this setting do set width properly. |
|
default_group: | (default: This setting sets default group for images without
defined group. If |
default_show_title: | |
(default: Defines that caption below the picture should be visible or not. Warning Currently this options does not work, I have no idea how to enable this feature in lightbox2. If you have any idea please do a pull request. |
|
download: | (default: Download remote images. |
Thumbnail directive¶
You can use it like:
.. thumbnail:: path/to/image.jpg
or:
.. thumbnail:: http://remote/image.jpg
You can pass options like to regular Sphinxs’ directives:
.. thumbnail:: http://remote/image.jpg
:download: true
All available arguments:
group: | If you set the same group for different images backend can group them. |
---|---|
class: | This can be used by backend to put some style. The straightforward use case it’s to define HTML classes here (LightBox2
backend put this classes on outer |
width: | Backend can use that to option to set width of the
image. This overrides Values like:
are accepted. |
height: | Backend can use that to option to set height of the
image. This overrides Values like:
are accepted. |
alt: | If image cannot be displayed, this text will be showen. |
download: | This overrides |
title: |
be used (it will define to show title or not).
It’s up to backend, how this will be displayed. Currently I have a problem with LightBox2 to make captions below thumbnails if you have any idea how to solve it please write. |
align: | (default: ‘’) Align the picture. LightBox2 backend uses Values like:
are accepted. Note You may want to wrap aligned element with: .. container:: clearfix
to fix document flow. |