sphinxcontrib-images 0.9.4¶
Project home: https://github.com/sphinx-contrib/images
PyPI: https://pypi.org/project/sphinxcontrib-images/
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 using a dictionary with options placed in conf.py
:
images_config = {
…
}
All available options with comments:
- backend
(default: ‘LightBox2’)
string
orcallable
If
string
it has to be the name of theentrypoint
registered in thesphinxcontrib.images.backend
group (look at the source ofsetup.py
in this project).Callable can be a function or a class which returns an instance of a backend to render images. The first argument is Sphinx’s app instance. Go to LightBox2 backend to see how to implement that.
Each backend should implement rendering
image_node
on specific outputs. If methods are not implemented, defaultimage
directive is a fallback.By default
LightBox2
backends natively support only HTML (other outputs are supported by fallback-image-directive).- override_image_directive
(default:
False
)True
orFalse
. It overrides the default Sphinximage
directive with thethumbnail
directive provided by this extension.- cache_path
(default :
_images
)Path, where to keep downloaded images. Relative to source (actually relative to
conf.py
) directory or absolute path.- requests_kwargs
(default:
{}
)Remote images are downloaded by requests. This
dict
keeps the keyword arguments that will be passed to theget
method.- default_image_width
(default:
100%
)Default width of an image. Backend can use this setting to set width properly.
- default_image_height
(default:
auto
)Default height of an image. Backend can use this setting to set width properly.
- default_group
(default:
None
)This setting sets the default group for images without a defined group. If
None
each image is placed in a separate group, which means that images are not grouped by default. Otherwise you can set a group name likedefault
to group all ungrouped images together.- default_show_title
(default:
False
)Defines whether a 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:
True
)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 regular Sphinxs’ directives:
.. thumbnail:: http://remote/image.jpg
:download: true
All available arguments:
- group
If you set the same group for different images the backend can group them.
- class
This can be used by the backend to apply some style.
The straightforward use case is to define HTML classes here (LightBox2 backend puts these classes on outer
a
element, not innerimg
).- width
Backend can use this option to set the width of the image. This overrides
default_image_width
from configuration.Values like:
percentage
100%
length with unit
100px
auto
are accepted.
- height
Backend can use this option to set the height of the image. This overrides
default_image_height
from configuration.Values like:
length with unit:
100px
auto
are accepted.
- alt
If image cannot be displayed, this text will be shown.
- download
This overrides
download
from configuration. You can set for particular image to download it or not. Works only for remote images.- title
If you do not define it,
default_show_title
configuration option will be used (it will define whether to show title or not).If you define this option but leave it empty, the content of the directive will be used as the title:
.. thumbnail:: image.jpg :title: This will be a title
If you define this option as text, it will be used as title:
.. thumbnail:: image.jpg :title: This is title This is description
It’s up to the 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
align-<left|center|right>
Sphinx html classes. By default alignment is not used at all.Values like:
left
center
right
are accepted.
Note
You may want to wrap aligned element with:
.. container:: clearfix
to fix document flow.
- show_caption
(default:
False
)Show the title as a caption below the image.
Warning
Enabling the caption nests the clickable image inside an HTML
figure
which gets the class if defined.This mays break existing styles.
To solve styles compatibility issues, you may use the legacy_class argument.
- legacy_class
Only applicable when show_caption is
True
.The classese specified are added to the clickable image.
The
figure
HTML element still gets the classes specified by the class argument.
Examples¶
Thumbnail¶
.. thumbnail:: img.jpg
Remote image (http)¶
.. thumbnail:: http://upload.wikimedia.org/wikipedia/meta/0/08/Wikipedia-logo-v2_1x.png
:download: false
Remote image (https)¶
.. thumbnail:: https://upload.wikimedia.org/wikipedia/meta/0/08/Wikipedia-logo-v2_1x.png
:download: false
Remote image (download http)¶
The image is downloaded and placed in _build/html/_images (for html build) making it availble locally.
.. thumbnail:: http://upload.wikimedia.org/wikipedia/meta/0/08/Wikipedia-logo-v2_1x.png
:download: true
Remote image (download https)¶
The image is downloaded and placed in _build/html/_images (for html build) making it availble locally.
.. thumbnail:: https://upload.wikimedia.org/wikipedia/meta/0/08/Wikipedia-logo-v2_1x.png
:download: true
Image with forced dimensions¶
.. thumbnail:: img.jpg
:width: 300px
:height: 100px
Image with additional class¶
.. thumbnail:: img.jpg
:class: framed
Image with description¶
.. thumbnail:: img.jpg
Descriptive description.
See also
Image alternative text¶
.. thumbnail:: http://a.b/non_existing_image.png
:alt: Cannot load this photo, but believe me it is nice.
Group images¶
.. thumbnail:: img.jpg
:group: group1
.. thumbnail:: https://upload.wikimedia.org/wikipedia/meta/0/08/Wikipedia-logo-v2_1x.png
:group: group1
Alignment¶
.. thumbnail:: img.jpg
:align: center
Reference via explicit target¶
Thumbnails can not, at present, be numbered like figures, hence they can not be referenced by :numref:, but they can be referenced by :ref:.
This is a reference to a thumbnail: :ref:`A thumbnail<my target>`.
Scroll until the image is not visible before clicking the link
to see the effect.
.. _my target:
.. thumbnail:: img.jpg
This is a reference to a thumbnail: A thumbnail. Scroll until the image is not visible before clicking the link to see the effect.