galaxy-iuc / standards

Documentation for standards and best practices from the Galaxy IUC
http://galaxy-iuc-standards.readthedocs.io/en/latest/
6 stars 16 forks source link

Need $PATH_TO_IMAGES for images in tool help #46

Closed peterjc closed 7 years ago

peterjc commented 7 years ago

Raised on the mailing list by Peter Briggs: http://dev.list.galaxyproject.org/Image-in-tool-XML-quot-help-quot-section-only-renders-when-installed-from-toolshed-tt4670961.html

peterjc commented 7 years ago

Cross reference #12 where this was initially documented - at the time there was apparently no need of $PATH_TO_IMAGES so is this a regression?

peterjc commented 7 years ago

Cross reference https://github.com/galaxyproject/galaxy/issues/1676 - it seems $PATH_TO_IMAGES is not universally supported.

pjbriggs commented 7 years ago

TLDR; I think the documentation is correct as it stands. $PATH_TO_IMAGES can be used but is not required and is essentially ignored.

More detail (if you're interested): after digging around, there seems to be two issues:

1. Support for $PATH_TO_IMAGES

According to comments in the Galaxy source code for the display_image_in_repository functions (appearing in lib/galaxy/webapps/galaxy/controllers/admin_toolshed.py and lib/galaxy/webapps/tool_shed/controllers/repository.py):

The following image definitions are all supported.  The former $PATH_TO_IMAGES is no longer required, and is now ignored.
        .. image:: https://raw.github.com/galaxy/some_image.png
        .. image:: $PATH_TO_IMAGES/some_image.png
        .. image:: /static/images/some_image.gif
        .. image:: some_image.jpg
        .. image:: /deep/some_image.png

(Furthermore, the set_image_paths function in tool_shed/util/shed_util_common.py explicitly strips $PATH_TO_IMAGES.)

Also the tests that I've performed are consistent with $PATH_TO_IMAGES not making a difference.

2. Images not being displayed in tool help sections depending on Galaxy configuration

In some contexts the images don't seem to be displayed in the tool help (for example if the tool is installed "locally" by hand, e.g. by editing the tool_conf.xml file to point to the tool XML file, rather than from a toolshed).

In these cases the issue is not related to $PATH_TO_IMAGES, but to the fact that Galaxy handles the rendering differently for locally versus toolshed-installed tools (cf https://github.com/galaxyproject/galaxy/issues/1676).

peterjc commented 7 years ago

Thanks for exploring this - the line "The former $PATH_TO_IMAGES is no longer required, and is now ignored." is pretty clear cut. Closing my pull request.