Merge pull request #2692 from bernt-matthias/topic/tool-dev-gcc21

GCC21: Tool dev tutorial updates

topics/dev/tutorials/tool-from-scratch/tutorial.md

@@ -98,7 +98,7 @@ Let's write a Bioconda recipe for the tool we want to package: [bellerophon](htt
 >    > <code-in-title>Bash</code-in-title>
 >    > ```bash
 >    > wget -O bellerophon.tar.gz https://github.com/davebx/bellerophon/archive/1.0.tar.gz
->    > sha256sum bellerophon.tar.gz # Copy the 64-character hexadecimal number that this outputs.
+> > sha256sum bellerophon.tar.gz # Copy the 64-character hexadecimal number that this outputs.
 >    > ```
 >    {: .code-in}
 >
@@ -396,6 +396,45 @@ user interface, then translate the user's selections back into the command to be
 on writing a wrapper. Although this section will cover the full process and many of the options available to
 anyone wrapping a tool, a more complete list is available in [the Galaxy tool docs](https://docs.galaxyproject.org/en/latest/dev/schema.html).
 
+## Installing Planemo
+
+Planemo is an important tool within the Galaxy development workflow. Although it will be covered in greater detail in the
+next section of this tutorial, one of its functions is necessary for the tool wrapper development. `planemo` is available
+via the python package manager `pip`. To that end, before beginning this section, please install `planemo` locally by running
+`planemo`. To that end, before beginning this section, please install planemo locally by running
+
+> <hands-on-title>Installing `planemo` via pip</hands-on-title>
+>
+> It is advised to install `planemo` in a virtual environment (step 1-2).
+>
+> 1. Create a virtual environment: `virtualenv -p python3 ~/.venv/`. Here `~/.venv/` is the path where the virtual environment should be crated and you may adapt the path to your needs. With `-p python3` we make sure that a `python` intepreter version 3 is used.
+> 2. Activate the virtual environment: `. ~/.venv/bin/activate`
+> 3. Install `planemo` `pip install planemo`
+{: .hands_on}
+
+Note that for using `planemo`from a new shell you will need to activate the python virtual environment again.
+
+> <hands-on-title>Testing `planemo` and getting help</hands-on-title>
+>
+> 1. In order to test if the installation worked execute
+>
+>    > <code-in-title>Input: Bash</code-in-title>
+>    > ```bash
+>    > planemo --version
+>    > ```
+>    {: .code-in}
+>
+>    > <code-in-title>Output</code-in-title>
+>    > This should output the version of `planemo`, e.g.
+>    > ```bash
+>    > planemo, version 0.74.3
+>    > ```
+>    {: .code-out}
+>
+> 2. `planemo --help` will show the available commands with a short desctiption (lint, test, and serve will be part of this tutorial)
+> 3. `planemo SUBCOMMAND --help` will show the usage information for the corresponding subcommand. Try to obtain the information for the `lint` subcommand.
+{: .hands_on}
+
 ## Initializing a Tool Wrapper
 
 Initializing a tool wrapper to be run in Galaxy is simple
@@ -881,7 +920,7 @@ runs the helloworld.py script present in the same folder as the tool xml, then e
 
 > <hands-on-title>Writing the command block</hands-on-title>
 >
-> The bellerophon command section would, based on the variables set previously, would be as follows. Add it to your tool XML.
+> The bellerophon command section, based on the variables set previously, would be as follows. Please add it to your tool XML.
 >
 > ```xml
 >     <command detect_errors="exit_code"><![CDATA[
@@ -910,7 +949,7 @@ runs the helloworld.py script present in the same folder as the tool xml, then e
 > ```
 {: .hands_on}
 
-inputs the variables set in the inputs and output sections to generate a full command to be run inside the Galaxy environment. When inside a conditional or
+The variables set in the inputs and output sections generate a full command to be run inside the Galaxy environment. When inside a conditional or
 section, the hierarchy is preserved using a period. For example
 
 ```txt
@@ -928,6 +967,20 @@ bellerophon --forward $forward_input --reverse $reverse_input --quality $quality
 && samtools sort --no-PG -O BAM -o `<outfile name generated by Galaxy>` -@ `<number of threads allocated>` merged_out.bam
 ```
 
+#### Symlinks
+
+The symlinks in the first two parts of this command serve to standardize the naming of files passed to the bellerophon command.
+For tools which require specific naming conventions, such as a standard prefix across all input files, or which require specified
+file extensions, this is necessary. When using non-symlinked files, Galaxy uses metadata for filetypes, but, by default, refers to
+files using a `.dat` etension. For example, had the symlinks not been used here, the command actually given would look like this:
+
+```bash
+bellerophon --forward <Galaxy_internal_reference_string>.dat --reverse <Galaxy_internal_reference_string>.dat ...
+```
+
+By adding the symlinks, the files are specified and will use proper names in the command. Although not strictly necessary for
+bellerophon, it is best practice for command legibility.
+
 ### Test section
 
 The test section is an easy way to ensure your tool wrapper functions as intended. It runs the tool and compares the output Galaxy returns against a
@@ -1072,53 +1125,9 @@ Among many other tasks it can:
 
 For more information on `planemo` see its extensive [documentation](https://planemo.readthedocs.io/).
 
-In this part of the tutorial we will start with installing `planemo` and then
+In this part of the tutorial we will be looking at `planemo` and
 see it in action linting, testing, and serving the tool.
 
-## Installing `planemo`
-
-`planemo` is available via the python package manager `pip` and `conda`.
-If you not have conda installed we suggest to use `pip` for installing `planemo`.
-
-> <hands-on-title>Installing `planemo` via pip</hands-on-title>
->
-> It is advised to install `planemo` in a virtual environment (step 1-2).
->
-> 1. Create a virtual environment: `virtualenv -p python3 ~/.venv/`. Here `~/.venv/` is the path where the virtual environment should be crated and you may adapt the path to your needs. With `-p python3` we make sure that a `python` intepreter version 3 is used.
-> 2. Activate the virtual environment: `. ~/.venv/bin/activate`
-> 3. Install `planemo` `pip install planemo`
-{: .hands_on}
-
-> <hands-on-title>Installing `planemo` via conda</hands-on-title>
->
-> 1. Install [miniconda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html)
-> 2. Create a conda environment with `planemo` installed `conda create -c conda-forge -c bioconda -n planemo planemo`
-> 3. Activate the conda environment `conda activate planemo`
-{: .hands_on}
-
-Note that for using `planemo`from a new shell you will need to activate the python/conda environment again.
-
-> <hands-on-title>Testing `planemo` and getting help</hands-on-title>
->
-> 1. In order to test if the installation worked execute
->
->    > <code-in-title>Bash</code-in-title>
->    > ```bash
->    > planemo --version
->    > ```
->    {: .code-in}
->
->    > <code-out-title></code-out-title>
->    > This should output the version of `planemo`, e.g.
->    > ```bash
->    > planemo, version 0.74.3
->    > ```
->    {: .code-out}
->
-> 2. `planemo --help` will show the available commands with a short desctiption (lint, test, and serve will be part of this tutorial)
-> 3. `planemo SUBCOMMAND --help` will show the usage information for the corresponding subcommand. Try to obtain the information for the `lint` subcommand.
-{: .hands_on}
-
 ## Using `planemo` to lint tools
 
 When linting a Galaxy tool `planemo` checks the sources for common errors and violations of best practice rules. Examples are: