sphinxcontrib-images 1.0.1

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 or callable

If string it has to be the name of the entrypoint registered in the sphinxcontrib.images.backend group (look at the source of setup.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, default image 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 or False. It overrides the default Sphinx image directive with the thumbnail 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 the get 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 like default 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 with local images:

.. thumbnail:: path/to/image.jpg

remote images:

.. thumbnail:: http://remote/image.jpg

MyST Markdown:

```{thumbnail} path/to/image.png
:width: 20 %
:alt: Firefox logo
```

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 inner img).

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

.. thumbnail:: https://www.sphinx-doc.org/en/master/_images/linux-logo.png
    :download: false

Remote image (download)

The image is downloaded and placed in _build/html/_images (for html build) making it availble locally.

.. thumbnail:: https://www.sphinx-doc.org/en/master/_images/linux-logo.png
    :download: true

Image with forced dimensions

.. thumbnail:: img.jpg
    :width: 300px
    :height: 100px

Image with additional class

.. thumbnail:: img.jpg
    :class: framed

Note

Requires a custom custom css file with a rule like:

.framed img { border: 2px solid black;}

Image with description

.. thumbnail:: img.jpg

    Descriptive description.

See also

Caption / title

Image alternative text

.. thumbnail:: http://a.b/non_existing_image.png
    :alt: Cannot load this photo, but believe me it is nice.
Cannot load this photo, but believe me it's nice.

Group images

.. thumbnail:: img.jpg
    :group: group1

.. thumbnail:: https://www.sphinx-doc.org/en/master/_images/linux-logo.png
    :group: group1

Alignment

.. thumbnail:: img.jpg
   :align: center

Caption / title

.. thumbnail:: img.jpg
    :title: Some title / caption.

.. thumbnail:: img.jpg
    :title: Some nice title to the picture.
    :show_caption: True
Some nice title to the picture.

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.

Indices and tables