Using 0.9.2 and sphinx 3.0.0 I get the following warnings

/usr/local/lib/python3.7/dist-packages/sphinxcontrib/images.py:239:  RemovedInSphinx40Warning: The app.add_stylesheet() is deprecated.  Please use app.add_css_file() instead.
--
08-Apr-2020 08:08:10 | app.add_stylesheet(os.path.relpath(dest_file_path, STATICS_DIR_PATH))
08-Apr-2020 08:08:10 | /usr/local/lib/python3.7/dist-packages/sphinxcontrib/images.py:237:  RemovedInSphinx40Warning: The app.add_javascript() is deprecated.  Please use app.add_js_file() instead.
08-Apr-2020 08:08:10 | app.add_javascript(os.path.relpath(dest_file_path, STATICS_DIR_PATH))

Sphinx 3.0.0 was released 05-04-2020, we should test the package against it.

I just did release 0.9.2 to PyPi and the release procedure is error-prone. Less now than when I release 0.9.0 and 0.9.1, but still error-prone.

At the moment the version number has to be changed in setup.py and sphinxcontrib/images.py manually.
release-to-pypi.sh (which does not interact with pypi.org) checks if the two version numbers match and it checks if the lightbox2 submodule is initialized. That is an improvement over the 0.9.0/0.9.1 jumble...

When doing a test upload to test.pypi.org with twine you can only use any given version number for one test, so if you test with version 0.9.2 you can not retest with 0.9.2, but only with 0.9.3 or 0.9.2.pre2. This error-prone, having to change version numbers (to add .preN) to test on test.pypi.org and then have to change them back (and rebuild) before uploading to pypi.org...

Of course it is doable, but I'm open for suggestions to make it less error-prone. Any ideas @t-b ?

(this definitely looks like sphinx or docutils bug, but I'd like to let you know + ask whether you have some clue)

In short

Enabling simultaneously sphinxcontrib.images and spinx.ext.todo or sphinx.ext.graphviz or various other plugins causes make epub to crash with dirty NotImplementedError while processing .. todo or similar directive.
Other targets (make html, make pdf) work fine.

Looks like this is caused by sole fact that sphinxcontrib.images defines explicit epub callback. This somehow changes the processing chain.

I repeated it both on python2+sphinx1.8.5 and python3+sphinx3.5.4.

Longer story

I have sphinx document which uses sphinxext.todo and contains some .. todo: directives (and also have my custom extension of similar kind, which also shows the issue). I recently added sphinxcontrib.images there. And, out of the sudden:

• make html and make pdf work fine
• make epub crashes during output writing with

…
  File "/home/marcink/.local/lib/python3.8/site-packages/sphinx/writers/html5.py", line 795, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: todo_node

I found out that disabling sphinxcontrib.images (commenting it out from extensions in conf.py) resolves the issue, then tried deeper.

sphinxcontrib.images has explicit epub callback:

Both sphinxext.todo and my custom extension do not have one..
For example sphinx/ext/todo.py has the following snippet in setup.py:

app.add_node(todo_node,
                 html=(visit_todo_node, depart_todo_node),
                 latex=(latex_visit_todo_node, latex_depart_todo_node),
                 text=(visit_todo_node, depart_todo_node),
                 man=(visit_todo_node, depart_todo_node),
                 texinfo=(visit_todo_node, depart_todo_node))

Editing this code (and editing my custom extension in the same way) resolves the issue. Once I I dirty-patched sphinx/ext/todo to:

app.add_node(todo_node,
                 html=(visit_todo_node, depart_todo_node),
                 epub=(visit_todo_node, depart_todo_node),
                 latex=(latex_visit_todo_node, latex_depart_todo_node),
                 text=(visit_todo_node, depart_todo_node),
                 man=(visit_todo_node, depart_todo_node),
                 texinfo=(visit_todo_node, depart_todo_node))

(added epub= line) whole issue disappeared, make epub started to work properly again.

So looks like „by default” sphinx nicely falls back to html callbacks while generating epub, but the fact that anybody in the ecosystem (here: sphinxcontrib.images) defined explicit epub handler changes something, and makes sphinx to work differently. And out of the sudden all directives which relied on fallback to html – cause crash.

At the moment https://sphinxcontrib-images.readthedocs.io/en/latest/ shows version 0.8.0. If it is not correct by performing a new build (when their package cache expires or is explicitly cleared) there might be a version number mismatch between some files.

What is the license for this repository? Missing license makes it unclear if/how this extension can be integrated and used within existing code bases.

I have enabled the plugin with sphinx 2.4.4 and it seems that it interferes somehow with the incremental build process and sphinx always makes a full build when this plugin is enabled.

Translation of text in image attributes miss.

How to reproduce

Create a project with sphinx-quickstart, add an image on index.rst and set a :title: and an :alt:.

Then, launch compilation with "make gettext". The content of :title: and of :alt: are not in the index.pot file.

tox.ini and .travis.yml contains much of the same information, according to [1] and [2] this can be done in a less redundant way.

.travis.yml is extremely verbose at the moment. [1] appears to offer a less verbose result, maybe because it is auto-generated by [2].

Good practices from the sphinx-contrib project template should be studied and maybe adopted (see [1]).

[1] https://github.com/sphinx-contrib/cookiecutter/tree/master/%7B%7Bcookiecutter.project_name%7D%7D
[2] https://pypi.org/project/tox-travis/

Produces different HTML output, which fails to work:

.. thumbnail:: <link-to-any-shields.io-svg>

Works when this extension is disabled / overriding is removed:

.. image:: <link-to-any-shields.io-svg>

• #36
• maybe refresh the documentation (there are super nice themes out ther in the wild)
• refresh readme (it's redundant with things in the documentation and I think it could be more synthetic
• use some linters (black?, ruff?) in the github actions
• use pre-commits ?
• aline version support with Sphinx (>3.6) (and get access to hints, f string and other fancy stuff)

Let me know which one you like and I'll do specific PRs

Let's drop support for and tests against Python 2 - Sphinx did that long ago.

@t-b's PR (sphinx 2.0 port) was merged and we should now do a release on pypi.org.

Which version number should we go with? Semantic versioning would suggest 0.9.0 since the new version is not incompatible with older versions of sphinx. (I still don't quite believe we still support 1.1 and python 2.7, but we do, don't we?)

We should update the documentation to reflect the new version number, new project URLs etc. Should we move to readthedocs in the process? I'm not 100% sure how documentation ends up on https://pythonhosted.org/sphinxcontrib-images/.

Hello,
I've just started working with sphinx and also just created a github account. This is kind of a How To Question or feature request.
I was amazed to find such a nice extension for HTML images.
Unfortunately I was not able to create a link to the image.

My first thought was: I should use .. figure:: instead of .. image:: (or .. thumbnail:: ) but the nice automatic integration of lightbox seems to be possible for ..image:: only.

Now for my Question:
Is there a way to link to the ..thumbnail:: or is there a way use the lightbox with fiigures?

What I've tried:

.. _imagetest:

.. thumbnail:: media/sphinx_jpgExample.jpg
 :title: This image has title.

 And more descriptions.

link to thumbnail: :ref:`imageLink` :ref:`own text<imageLink>`

Greetings
Falk

TL; DR; A second maintainer would be welcome, if you're interested let me know. Until summer 2021 I have limited time to dedicated to merging PRs and handling issues.

I only intended to help complete spinus#56 by leaving a comment, to gain Sphinx 2.x support which I needed at the time, but to move forward the project ended up under the https://github.com/sphinx-contrib umbrella with me as admin (on https://pypi.org/project/sphinxcontrib-images/ as well).

There are some fine issues waiting to be fixed and some fine looking PRs to fix some of the issues, but I have had very little time to devote to the project since May 2020 and I will continue to have little time until late spring or early summer 2021.

Adding a second maintainer or co-maintainer could help move the project forward at a more steady pace. The intention behind joining the https://github.com/sphinx-contrib repo was to ensure continued development, since it would be easy for others to take over.

Let me know if you're interested. Tasks would include one or more of answering issue tickets, reviewing PRs, merging PRs, releasing to PyPi. I'm no expert in any of this, but I'll be happy to help get new co-maintainers started on the tasks.

Update June 2023
I am still looking for a second maintainer as of June 2023 - regardless of my time to invest in the project it would be smart to have a second person with knowledge of the project.

There are still some fine issues to fix and support for figures to be added. I do not use the extension at the moment, because figures are not supported, but support can be added and I'd like to do so (or have someone else do it of course).

At the moment there is only one collective integration test performed by Tox (via GitHub Actions, previously via Travis CI), and that is make -C docs html(see https://github.com/sphinx-contrib/images/blob/master/tox.ini).

That test only fails the package docs fail to build, it does not test if the docs are actually built correctly. I believe #23 has shown this. With #23 (commit 4d65651) and images_config = {'cache_path': '_custom_cache'} in conf.py downloaded/cached images are/were not copied to _build/html/_images correctly.

A manual test reveals this, but the amount of manual tests which needs to be conducted are growing. For version 0.9.3 a bug was fixed which caused docs to always rebuild files which did not change, that is also not guarded against by any tests.

Any contributions are welcome. My idea at the moment is to write tests which build the docs and parse the build log or parse the generated html-files.

It seems like the included version of LightBox2 is pointed at a specific, very old commit, which includes an old version of jquery.
The newer versions of LightBox2 use later versions of jquery.

Actually, It looks like it's a git submodule that was committed 7 years ago and has not been updated since....

A new release should be made to support Sphinx versions above 3.2.1 and should be tested against Python version above 9.

This issue serves to list and discuss tasks.

• Merge #39
• Update tox.inì to test against newer versions of Sphinx and Python (and run them / find a place to run them - maybe Github Actions)
• Merge #38
• Drop Python2 support (#37)

I upgraded Sphinx. Now i had version 4.

There is mistake, when i make html:

Extension error (sphinxcontrib.images): Handler <function install_backend_static_files at 0x046DD1E0> for event 'env-updated' threw an exception (exception: 'Sphinx' object has no attribute 'add_stylesheet')

At the moment when I hover an image the mouse pointer change from normal pointer to link pointer. Which according to me is confusing to the end user. Is it possible to customize it to zoom-in ?

Is it possible to disable the white flash during a transition of the LightBox2 backend?

For image comparisons, it makes it more or less impossible to quickly snap back and forth and compare.

I want to build my documentation using GIF images. GIF are natively not supported by latex. a wrokaround suggested by the sphinx team is the following:

Sphinx extends the standard docutils behavior by allowing an asterisk for the extension:

.. image:: gnu.*

Sphinx then searches for all images matching the provided pattern and determines their type. Each builder then chooses the best image out of these candidates. For instance, if the file name gnu.* was given and two files gnu.pdf and gnu.png existed in the source tree, the LaTeX builder would choose the former, while the HTML builder would prefer the latter. Supported image types and choosing priority are defined at Available builders.

When I try to use this method with the lib I get the following error:

ValueError: Image URI `_images/google.*` have to be local relative or absolute path to image, or remote address.

It's coming from this function that doesn't test for "*" files.

Can we add support for figure directives as well as image directives?

TL; DR; A second maintainer would be welcome, if you're interested let me know. Until summer 2021 I have limited time to dedicated to merging PRs and handling issues.

I only intended to help complete spinus#56 by leaving a comment, to gain Sphinx 2.x support which I needed at the time, but to move forward the project ended up under the https://github.com/sphinx-contrib umbrella with me as admin (on https://pypi.org/project/sphinxcontrib-images/ as well).

There are some fine issues waiting to be fixed and some fine looking PRs to fix some of the issues, but I have had very little time to devote to the project since May 2020 and I will continue to have little time until late spring or early summer 2021.

Adding a second maintainer or co-maintainer could help move the project forward at a more steady pace. Let me know if you're interested. Tasks would include one or more of answering issue tickets, reviewing PRs, merging PRs, releasing to PyPi. I'm no expert in any of this, but I'll be happy to help get new co-maintainers started on the tasks.