Review diagrams/images in docs and potentially resize to a consistent maximum or use a plugin to make thumbnails

[stichbury]

Introduction

in PR #2625 I posted this response on taking a look through the diagrams in our docs:

In the section that @astrojuanlu flags (https://docs.kedro.org/en/stable/visualisation/kedro-viz_visualisation.html#automatic-visualisation-updates) there is a pretty large graphic (long vertical drop) and I'm wondering if it would be sensible for me to go through and resize all the images to either a fixed height or width. I'll ask @Mackay031 what he recommends.

Also, am I right in thinking there is a plugin for Sphinx where if you have an image relatively small, you can click on it and it opens it larger so you can review detail? That may be a good option to add so we can reduce sizes to a common maximum for easy scrolling and reading, whilst retaining details.

[stichbury]

The plugin might be this one https://github.com/sphinx-contrib/images

[Gundalai-Batkhuu]

@stichbury I would like to try working on this issue using the plugin

The plugin might be this one https://github.com/sphinx-contrib/images

[astrojuanlu]

@Gundalai-Batkhuu https://github.com/kedro-org/kedro/issues/2287#issuecomment-1772379988

[Gundalai-Batkhuu]

@astrojuanlu It looks like to use this plugin, the source docs need to have .rst extension. In example, the inline reference of the large image mentioned above should become:

.. thumbnail:: docs/source/meta/images/pipeline_visualisation_with_layers.png

from:

"../meta/images/pipeline_visualisation.png"

If we do that, we can make thumbnails and adjust the size of the photos. What do you think?

[astrojuanlu]

We will not change the docs to rst - but the good news is that you can evaluate rst inside myst

```{eval-rst}
.. figure:: img/fun-fish.png
  :width: 100px
  :name: rst-fun-fish

  Party time!

A reference from inside: :ref:`rst-fun-fish`

A reference from outside: :ref:`syntax/directives/parsing`

[Gundalai-Batkhuu]

@astrojuanlu Thanks for the help. It worked. I've made the following changes:

• Register the plugin in conf.py
• Add the plugin config dict in conf.py
• Converted inline references of all images in kedro-viz_visualisation.md
• Set the global config for image width to 70%.

Now the images look like this:

[Gundalai-Batkhuu]

I have the following questions:

• Should I change inline refs of all images in the doc pages?
• Should I set the global width for all images from the conf.py or should I change widths for large images only?

[astrojuanlu]

Let's start with a PR of what you already have @Gundalai-Batkhuu , and we can discuss about extending it to other parts of the code

[astrojuanlu]

For future reference, in #3238 we found that https://pypi.org/project/sphinxcontrib-images/ has a bug when rendering the thumbnails on mobile. alternative solutions (or a fix upstream) are needed.