Merge branch 'main' into fix/github-issue-975

doc-environment.yml

@@ -13,6 +13,7 @@ dependencies:
   - jsonschema
   - gitpython
   - sphinx
+  - pip
   - pip:
     - sphinxcontrib-napoleon
   - sphinx-argparse

docs/tutorial/basics.rst

@@ -113,6 +113,10 @@ In other words, Snakemake will replace ``{input}`` with ``data/genome.fa data/sa
 The shell command invokes ``bwa mem`` with reference genome and reads, and pipes the output into ``samtools`` which creates a compressed `BAM <https://en.wikipedia.org/wiki/Binary_Alignment_Map>`_ file containing the alignments.
 The output of ``samtools`` is redirected into the output file defined by the rule with ``>``.
 
+.. sidebar:: Note
+
+  It is best practice to have subsequent steps of a workflow in separate, unique, output folders. This keeps the working directory structured. Further, such unique prefixes allow Snakemake to quickly discard most rules in its search for rules that can provide the requested input. This accelerates the resolution of the rule dependencies in a workflow.
+
 When a workflow is executed, Snakemake tries to generate given **target** files.
 Target files can be specified via the command line.
 By executing
@@ -227,7 +231,9 @@ We add the following rule beneath the ``bwa_map`` rule:
 
 .. sidebar:: Note
 
-  It is best practice to have subsequent steps of a workflow in separate, unique, output folders. This keeps the working directory structured. Further, such unique prefixes allow Snakemake to quickly discard most rules in its search for rules that can provide the requested input. This accelerates the resolution of the rule dependencies in a workflow.
+  In the shell command above we split the string into two lines, which are however automatically concatenated into one by Python.
+  This is a handy pattern to avoid too long shell command lines. When using this, make sure to have a trailing whitespace in each line but the last, 
+  in order to avoid arguments to become not properly separated.
 
 This rule will take the input file from the ``mapped_reads`` directory and store a sorted version in the ``sorted_reads`` directory.
 Note that Snakemake **automatically creates missing directories** before jobs are executed.
@@ -360,21 +366,6 @@ But for now, this is enough so that we can add the following rule to our Snakefi
             "samtools mpileup -g -f {input.fa} {input.bam} | "
             "bcftools call -mv - > {output}"
 
-
-.. sidebar:: Note
-
-  When **splitting long shell commands across multiple lines**, make sure to **include whitespace at the end of each line**.
-  As the strings from each line are simply concatenated, this can otherwise lead to erroneous shell commands and weird errors.
-  For example, further splitting the first of the commands in the current example should not be done like this:
-
-  .. code:: python
-
-      "samtools mpileup"
-      "-g -f {input.fa} {input.bam}"
-
-  This would concatenate to the command ``"samtools mpileup-g -f {input.fa} {input.bam}"`` and consequently throw the error: ``[main] unrecognized command 'mpileup-g'``.
-
-
 With multiple input or output files, it is sometimes handy to refer to them separately in the shell command.
 This can be done by **specifying names for input or output files**, for example with ``fa=...``.
 The files can then be referred to in the shell command by name, for example with ``{input.fa}``.