From 08cb278cc9612a70dcb9dd77ff3bfbdfd333ce2b Mon Sep 17 00:00:00 2001 From: Nicola Soranzo Date: Thu, 26 Oct 2017 15:36:17 +0100 Subject: [PATCH] Add various elements to the Tool XML doc page In particular: - macros - edam_topics - edam_operations - environment_variables and subelement - request_param_translation and subelements Also: - reorder elements to follow IUC coding style - in examples: - use lowercase ``true`` and ``false`` for boolean attributes - add/use single quotes - minor doc fixes --- doc/schema_template.md | 33 ++++++---- lib/galaxy/tools/xsd/galaxy.xsd | 106 ++++++++++++++++++-------------- 2 files changed, 81 insertions(+), 58 deletions(-) diff --git a/doc/schema_template.md b/doc/schema_template.md index 977853019ce..01cb514352a 100644 --- a/doc/schema_template.md +++ b/doc/schema_template.md @@ -15,8 +15,23 @@ number of tutorials on building Galaxy tools that would better serve that purpos $tag:tool://element[@name='tool'] $tag:tool|description://element[@name='tool']//element[@name='description'] +$tag:tool|macros://complexType[@name='Macros'] +$tag:tool|edam_topics://complexType[@name='EdamTopics'] +$tag:tool|edam_operations://complexType[@name='EdamOperations'] +$tag:tool|requirements://complexType[@name='Requirements'] +$tag:tool|requirements|requirement://complexType[@name='Requirement'] +$tag:tool|requirements|container://complexType[@name='Container'] +$tag:tool|code://complexType[@name='Code'] +$tag:tool|stdio://complexType[@name='Stdio'] +$tag:tool|stdio|exit_code://complexType[@name='ExitCode'] hide_attributes +$tag:tool|stdio|regex://complexType[@name='Regex'] hide_attributes $tag:tool|version_command://complexType[@name='VersionCommand'] $tag:tool|command://element[@name='tool']//element[@name='command'] hide_attributes +$tag:tool|environment_variables://complexType[@name='EnvironmentVariables'] +$tag:tool|environment_variables|environment_variable://complexType[@name='EnvironmentVariable'] +$tag:tool|configfiles://complexType[@name='ConfigFiles'] +$tag:tool|configfiles|configfile://complexType[@name='ConfigFile'] +$tag:tool|configfiles|inputs://complexType[@name='ConfigInputs'] $tag:tool|inputs://complexType[@name='Inputs'] $tag:tool|inputs|section://complexType[@name='Section'] $tag:tool|inputs|repeat://complexType[@name='Repeat'] @@ -36,11 +51,12 @@ $tag:tool|inputs|param|sanitizer|valid|remove://complexType[@name='SanitizerVali $tag:tool|inputs|param|sanitizer|mapping://complexType[@name='SanitizerMapping'] $tag:tool|inputs|param|sanitizer|mapping|add://complexType[@name='SanitizerMappingAdd'] $tag:tool|inputs|param|sanitizer|mapping|remove://complexType[@name='SanitizerMappingRemove'] -$tag:tool|configfiles://complexType[@name='ConfigFiles'] -$tag:tool|configfiles|configfile://complexType[@name='ConfigFile'] -$tag:tool|configfiles|inputs://complexType[@name='ConfigInputs'] -$tag:tool|environment_variables://complexType[@name='EnvironmentVariables'] -$tag:tool|environment_variables|environment_variable://complexType[@name='EnvironmentVariable'] +$tag:tool|request_param_translation://complexType[@name='RequestParameterTranslation'] +$tag:tool|request_param_translation|request_param://complexType[@name='RequestParameter'] +$tag:tool|request_param_translation|request_param|append_param://complexType[@name='RequestParameterAppend'] +$tag:tool|request_param_translation|request_param|append_param|value://complexType[@name='RequestParameterAppendValue'] +$tag:tool|request_param_translation|request_param|value_translation://complexType[@name='RequestParameterValueTranslation'] +$tag:tool|request_param_translation|request_param|value_translation|value://complexType[@name='RequestParameterValueTranslationValue'] $tag:tool|outputs://complexType[@name='Outputs'] $tag:tool|outputs|data://complexType[@name='Data'] $tag:tool|outputs|data|filter://complexType[@name='OutputFilter'] @@ -68,13 +84,6 @@ $tag:tool|tests|test|output_collection://complexType[@name='TestOutputCollection $tag:tool|tests|test|assert_command://group[@name='TestParamElement']//element[@name='assert_command'] $tag:tool|tests|test|assert_stdout://group[@name='TestParamElement']//element[@name='assert_stdout'] $tag:tool|tests|test|assert_stderr://group[@name='TestParamElement']//element[@name='assert_stderr'] -$tag:tool|code://complexType[@name='Code'] -$tag:tool|requirements://complexType[@name='Requirements'] -$tag:tool|requirements|requirement://complexType[@name='Requirement'] -$tag:tool|requirements|container://complexType[@name='Container'] -$tag:tool|stdio://complexType[@name='Stdio'] -$tag:tool|stdio|exit_code://complexType[@name='ExitCode'] hide_attributes -$tag:tool|stdio|regex://complexType[@name='Regex'] hide_attributes $tag:tool|help://element[@name='tool']//element[@name='help'] $tag:tool|citations://complexType[@name='Citations'] $tag:tool|citations|citation://complexType[@name='Citation'] diff --git a/lib/galaxy/tools/xsd/galaxy.xsd b/lib/galaxy/tools/xsd/galaxy.xsd index 9c03aaa8864..54b54510f5c 100644 --- a/lib/galaxy/tools/xsd/galaxy.xsd +++ b/lib/galaxy/tools/xsd/galaxy.xsd @@ -44,7 +44,7 @@ A ``data_source`` tool contains a few more relevant attributes. - + @@ -197,6 +197,22 @@ communicating with an external data source application (the default is ``get``). + + + Frequently, tools may require the same XML +fragments be repeated in a file (for instance similar conditional branches, +repeated options, etc...) or among tools in the same repository. Galaxy tools +have a macro system to address this problem. + +For more information, see https://planemo.readthedocs.io/en/latest/writing_advanced.html#macros-reusable-elements + + + + + + + + Describe the backend Python action to execute for this Galaxy tool. @@ -402,7 +418,7 @@ elements in the ``field_names`` metadata element associated with the selected input dataset. ```xml - + @@ -1376,7 +1392,7 @@ Define tests for extra files corresponding to an output collection. ``output_collection`` directives should specify a ``name`` and ``type`` attribute to describe the expected output collection as a whole. -Expectations about collecton contents are described using child ``element`` +Expectations about collection contents are described using child ``element`` directives. For nested collections, these child ``element`` directives may themselves contain children. @@ -1486,7 +1502,7 @@ etc...). `` tag set contained within the tool's ```` tag set. +```` tag set contained within the tool's ```` tag set. ]]> @@ -1515,7 +1531,7 @@ many of the default assertion tags that come with Galaxy and examples of each can be found below. The implementation of these tags are simply Python functions defined in the -[galaxy.tools.verify.asserts](https://github.com/galaxyproject/galaxy/tree/dev/lib/galaxy/tools/verify/asserts) +[/lib/galaxy/tools/verify/asserts](https://github.com/galaxyproject/galaxy/tree/dev/lib/galaxy/tools/verify/asserts) module. ]]> @@ -1612,9 +1628,9 @@ module. - `` tag within the ```` tag set -maps to a command line parameter within the [command](#tool-command) tag. Most + @@ -1687,13 +1703,13 @@ statement. A good example tool that demonstrates many conditional parameters is ```xml - + - + @@ -1956,7 +1972,7 @@ The XML configuration is relatively trivial for sections: ```xml -
+
@@ -2035,7 +2051,7 @@ The ``size`` parameter can be two dimensional, if it is the textbox will be rendered on the tool form as a text area instead of a single line text box. ```xml - + ``` As of 17.01, ``text`` parameters can also supply a static list of preset @@ -2418,7 +2434,7 @@ template if the parameter is ``false`` or not checked by the user. Only valid if Used only if ``type`` attribute -value is ``text``. To create a multi-line text box add an ``area="True"`` +value is ``text``. To create a multi-line text box add an ``area="true"`` attribute to the param tag. This can be one dimensional (e.g. ``size="40"``) or two dimensional (e.g. ``size="5x25"``). @@ -2558,9 +2574,9 @@ uses an interpreted executable. In this case a Perl script is shipped with the tool and the directory of the tool itself is referenced with ``$__tool_directory__``. ```xml - - perl $__tool_directory__/xpath -q -e '$expression' '$input' > '$output' - + '$output' +]]]]> ``` The following example demonstrates accessing metadata from datasets. Metadata values @@ -2582,7 +2598,7 @@ according to the Metadata spec. #set genome = $input.metadata.dbkey #set datatype = $input.datatype mkdir -p output_dir && - python $__tool_directory__/extract_genomic_dna.py + python '$__tool_directory__/extract_genomic_dna.py' --input '$input' --genome '$genome' #if $input.is_of_type("gff"): @@ -2768,12 +2784,12 @@ dataset for the contained input of the type specified using the ``type`` tag. ]]> - + Name of Cheetah variable to create for converted dataset. - + The short extension describing the datatype to convert to - Galaxy must have a datatype converter from the parent input's type to this. @@ -3052,7 +3068,7 @@ ensures that a dbkey is present and that FASTA indices in the ``fasta_indexes`` tool data table are present. ```xml - + @@ -3855,7 +3871,7 @@ conditionals are accessed using a hash named after the conditional. - + @@ -4017,7 +4033,7 @@ supplied file. @@ -4126,7 +4142,7 @@ column="1" />`` tag does), then it should be changed to ``equCab2`` (which is th @@ -4477,7 +4493,7 @@ tool config. This file is then used in the ``command`` block of the tool as follows: ```xml -bash "$__tool_directory__/r_wrapper.sh" "$script_file" +bash '$__tool_directory__/r_wrapper.sh' '$script_file' ``` ]]> @@ -4568,7 +4584,7 @@ An example that leverages a Python script (e.g. ``count_reads.py``) shipped with the tool might be: ```xml -python $__tool_directory__/count_reads.py +python '$__tool_directory__/count_reads.py' ``` Examples are included in the test tools directory including: @@ -4583,7 +4599,7 @@ Examples are included in the test tools directory including: - $__tool_directory__/``.]]> + '$__tool_directory__/'``.]]> @@ -4592,9 +4608,7 @@ Examples are included in the test tools directory including: - tag set - it contains a set of tags. - ]]> + @@ -4603,19 +4617,19 @@ Examples are included in the test tools directory including: - tag set ( used only in "data_source" tools ) - the external data source application may send back parameter names like "GENOME" which must be translated to "dbkey" in Galaxy.]]> + - + - Each of these maps directly to a remote_name value + Each of these maps directly to a ``remote_name`` value - + The string representing the name of the parameter in the remote data source @@ -4625,7 +4639,7 @@ Examples are included in the test tools directory including: - The default value to use for galaxy_name if the remote_name parameter is not included in the request + The default value to use for ``galaxy_name`` if the ``remote_name`` parameter is not included in the request @@ -4657,7 +4671,7 @@ Examples are included in the test tools directory including: - tag set if galaxy_name="URL" - some remote data sources ( e.g., Gbrowse, Biomart ) send parameters back to Galaxy in the initial response that must be added to the value of "URL" prior to Galaxy sending the secondary request to the remote data source via URL.]]> + @@ -4672,7 +4686,7 @@ The text to use to join the requested parameters together (example ``separator=" @@ -4687,7 +4701,7 @@ The text to use to join the param name to its value (example ``join="="``). - tag set - allows for appending a param name / value pair to the value of URL. + @@ -4718,7 +4732,7 @@ Any valid HTTP request parameter name. The name / value pair must be received fr - tag set the parameter value received from a remote data source may be named differently in Galaxy, and this tag set allows for the value to be appropriately translated.]]> + @@ -4727,7 +4741,7 @@ Any valid HTTP request parameter name. The name / value pair must be received fr - tag set - allows for changing the data type value to something supported by Galaxy. + `` tags. A tool can have any number of EDAM topic references. ```xml - - + + topic_2269 - + ``` ]]> @@ -5368,10 +5382,10 @@ Container tag set for the ```` tags. A tool can have any number of EDAM operation references. ```xml - - + + operation_3434 - + ``` ]]>