`` element can be used instead of a ````. Beware that parameters inside a hidden section still have a value set, which is used when creating the job command, while in a "closed" conditional the non-visible parameters don't have a value. Command tag ----------- The command tag is one of the most important parts of the tool, next to the user-facing options. It should be highly legible. Command Formatting ^^^^^^^^^^^^^^^^^^ The command tag should be started and finished by a CDATA tag, allowing direct use of characters like the ampersand (``&``) without needing XML escaping (``&``). .. code:: xml `Wikipedia has more on CDATA `__ All Cheetah variables for text parameters, input and output files must be single-quoted, e.g. ``'${var_name}'``. For composite datatypes the recommended attribute to access the associated directory name differs for inputs (e.g. ``$input.extra_files_path``) versus outputs (e.g. ``$output.files_path``). This difference is historical, and it is hoped this will be harmonised in a future Galaxy release. If you need to execute more than one shell command, concatenate them with a double ampersand (``&&``), so that an error in a command will abort the execution of the following ones. Exit Code Detection ^^^^^^^^^^^^^^^^^^^ Unless the tool has special requirements, you should take advantage of the exit code detection provided by Galaxy, in lieu of using the ```` tags. This can be done by adding a ``detect_errors`` tag to your ```` block like so: .. code:: xml ... This will automatically fail the tool if the exit code is non-zero, or if the phrases ``error:`` or ``exception:`` appear in STDERR. Help tag -------- The help tag should be started and finished by a CDATA tag. .. code:: xml `http://en.wikipedia.org/wiki/CDATA `__ Inside the help tag you should describe the functionality of your tool. The help tag is to the ``help=""`` attribute as a man page is to the ``--help`` flag. The help tag should cover the tools functionality, use cases, and even known issues in detail. The help tag is a good place to provide examples of how to run the tool and discuss specific subcases that your users might be interested in. Including Images ^^^^^^^^^^^^^^^^ If you have produced images detailing how your tool works (e.g. `bedtools`_), it might be nice for those images to be included in the Galaxy tool documentation! Images should be placed in a subdirectory, ``./static/images/``, and referenced in your tool help as ``.. image:: my-picture.png``. This can be seen in the IUC's wrappers, such as the one for the bedtools `slop`_ command. Generating Indices ------------------ Occasionally data needs to be indexed (e.g. bam, fasta) files. When data is indexed, those indices should be generated in the current working directory rather than alongside the input dataset. This is part of the tool contract, you can read from your inputs, but only write to your outputs and CWD. It's convenient to do something like: .. code:: console ln -sfn "${input_fasta}" tmp.fa; before data processing in order to be able to easily generate the indices without attempting to write to a (possibly) read-only data source. Datatypes --------- For now, the recommended practice is to push new datatypes to the `Galaxy repository`_. Data Managers ------------- TODO Coding Style ------------ * 4 spaces indent * Order of XML elements: * `description`_ * `macros`_ * `edam_topics`_ * `edam_operations`_ * `xrefs`_ * [parallelism] * `requirements`_ * [code] * `stdio`_ * `version_command`_ * `command`_ * environment_variables * `configfiles`_ * `inputs`_ * `request_param_translation`_ * `outputs`_ * `tests`_ * `help`_ * `citations`_ * Cheetah code should also be indented and mainly `PEP8`_ conformant * XML elements should normally have all attributes on a single line for easier searchability, but for large XML elements the ``label`` and ``help`` attributes can be on a new line. * param names should be readable and understandable, e.g. using the long option name of the wrapped tool * Order of parameter attributes: * name * argument * type * format * min | truevalue * max | falsevalue * value | checked * optional * label * help * Python code should be Python3-compatible and `PEP8`_ conformant. Imports should follow the `smarkets`_ style. .. _description: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-description .. _xrefs: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-xrefs .. _macros: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-macros .. _edam_topics: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-edam-topics .. _edam_operations: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-edam-operations .. _requirements: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-requirements .. _stdio: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-stdio .. _version_command: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-version-command .. _command: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-command .. _configfiles: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-configfiles .. _inputs: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-inputs .. _request_param_translation: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-request-param-translation .. _outputs: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-outputs .. _tests: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-tests .. _help: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-help .. _citations: https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-citations .. _bedtools: http://bedtools.readthedocs.org/en/latest/content/tools/slop.html .. _slop: https://github.com/galaxyproject/tools-iuc/blob/master/tools/bedtools/slopBed.xml .. _Galaxy repository: https://github.com/galaxyproject/galaxy .. _PEP8: https://www.python.org/dev/peps/pep-0008/ .. _smarkets: https://github.com/PyCQA/flake8-import-order/blob/master/tests/test_cases/complete_smarkets.py .. _bio.tools: https://bio.tools .. _EDAM: http://edamontology.org