Improvements to help terms & tool help.

[jmchilton]

What is in the PR

• Allow tools to declare markdown help.
• Allow tools to reference help terms from their Markdown tools.
• Auto generate help terms for each datatype from values in datatypes_conf.xml
• Add permanent links for each help term - both the auto generated ones and the YAML specified
  ones.
• Add some initial help terms for collection operations.
• Use new help term for "map over" from tool form.

Motivation

I had the request to define "map over" in #18698. I don't want to do that in the context of a narrow tool - I'd rather make some progress on some longer term goals in dev. This is some infrastructure for embedding help terms (added as part of #17569) into tools - along with the option to allow Markdown help in tools (a long requested feature - xref #6230).

Screenshots

Map Over Terminology

One thing I did was to restore the term "map over" back into the tool form. It was removed a while ago but I think it is important to distinguish running a tool on a bunch of datasets vs. running a tool on collections. The different is important in terms of sample tracking and workflow construction.

24.1:

After:

Embedding Help Links into Tool Help:

Help Terms for Datatypes ( per request from @bgruening )

Perm Links for Galaxy Terms

How to test the changes?

(Select all options that apply)

• I've included appropriate automated tests.
• This is a refactoring of components with existing test coverage.
• Instructions for manual testing are as follows:
  1. [add testing steps and prerequisites here if you didn't write automated tests covering all your changes]

License

• I agree to license these and all my past contributions to the core galaxy codebase under the MIT license.

[mvdbeek]

Excellent, that is amazing!

[bgruening]

It's a great idea!

Can we extend this to automatically include the filetype descriptions from datatypes_conf? Something like <HelpText text="NetCDF" extension="netcdf" />

@PlushZ Sorry, but I think @jmchilton implemented markdown support here already.

@jmchilton should we put the type="markdown" behind a tool profile version?

[jmchilton]

From @bgruening

Can we extend this to automatically include the filetype descriptions from datatypes_conf? Something like

It required rewriting a lot of stuff to use the API now and hence a pinia store but I have done this I think. There are now dynamic "help term URIs" for each datatype extension. I've added screenshots for this above.

[jmchilton]

From @bgruening

@jmchilton should we put the type="markdown" behind a tool profile version?

I've updated the XSD to include allowing setting this... but I don't think so is the answer. We don't usually block features based on profile version right? We use it more to fix broken things or things we don't like in newer profiles. We aren't going to not load the help in older Galaxies and the best we could do is issue a warning about the help not rendering correct on older Galaxies during development. The thing I would do is to starting in 25.0 - make that profile version or newer use Markdown by default. Markdown is omnipresent and fewer people know RST every passing year.

[bgruening]

Very cool! I added an issue for the galaxy-language-server to add support for this.
Can you maybe add a test tool / documentation that shows how to use the syntax and what do you think about testing image embedding with the new markdown help?

Thanks a lot, @jmchilton!
I will ask some friends to help improve the datatype annotations.

[jmchilton]

what do you think about testing image embedding with the new markdown help?

Almost a decade ago I wrote the implementation "drives me crazy" #1676 and as far as I'm aware nothing has changed 😆 😭. We won't really know if it works until we have an installed tool shed tool that uses the syntax. My guess is that it should just work though because the helper function that rewrites the paths is the same helper function that corrects headers tags and I have tested that header tags are properly corrected. The target code works on the generated HTML so it should be the same for rst and markdown more or less I think. I would not spend my time setting up a test for that - someone will report it if it doesn't work and then we will have an easier test bed for fixing any issues that arise.

If there is tool shed side code that doesn't work with the new syntax I have been told we're not updating the tool shed so I think that will likewise just need to be something to push off.

[bgruening]

I'm totally fine with that :) Thanks a lot John!

[jmchilton]

Can you maybe add a test tool / documentation that shows how to use the syntax...

I added some test tools that exercise various features of rst and markdown help.