feat: Add threading support (#3649)

<!-- Ensure that the PR title follows conventional commit style (<type>:
<description>)-->
<!-- Possible types are here:
https://github.com/commitizen/conventional-commit-types/blob/master/index.json
-->

<!-- Add a description of your PR here-->

### QC
<!-- Make sure that you can tick the boxes below. -->

* [x] I confirm that I have followed the [documentation for contributing
to
`snakemake-wrappers`](https://snakemake-wrappers.readthedocs.io/en/stable/contributing.html).

While the contributions guidelines are more extensive, please
particularly ensure that:
* [x] `test.py` was updated to call any added or updated example rules
in a `Snakefile`
* [x] `input:` and `output:` file paths in the rules can be chosen
arbitrarily
* [x] wherever possible, command line arguments are inferred and set
automatically (e.g. based on file extensions in `input:` or `output:`)
* [x] temporary files are either written to a unique hidden folder in
the working directory, or (better) stored where the Python function
`tempfile.gettempdir()` points to
* [x] the `meta.yaml` contains a link to the documentation of the
respective tool or command under `url:`
* [x] conda environments use a minimal amount of channels and packages,
in recommended ordering


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Enjoy enhanced customization with new configuration options, including
an embedded link for quick access to command-line documentation.
- Merging operations now support two processing threads, improving
performance while ensuring appropriate thread usage.
- Enhanced error handling for thread management, providing clearer
feedback for users.
- **Documentation**
- Updated documentation structure to include new parameters for improved
clarity.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

bio/picard/mergesamfiles/meta.yaml

@@ -1,14 +1,15 @@
 name: picard MergeSamFiles
 description: |
   Merge sam/bam files using picard tools.
+url: https://broadinstitute.github.io/picard/command-line-overview.html#MergeSamFiles
 authors:
   - Julian de Ruiter
 input:
   - sam/bam files
 output:
   - merged sam/bam file
+params:
+  - java_opts: additional arguments to be passed to the java compiler, e.g. "-XX:ParallelGCThreads=10" (not for `-XmX` or `-Djava.io.tmpdir`, since they are handled automatically)
+  - extra: additional program arguments
 notes: |
-  * The `java_opts` param allows for additional arguments to be passed to the java compiler, e.g. "-XX:ParallelGCThreads=10" (not for `-XmX` or `-Djava.io.tmpdir`, since they are handled automatically).
-  * The `extra` param allows for additional program arguments.
   * `--TMP_DIR` is automatically set by `resources.tmpdir`
-  * For more information see, https://broadinstitute.github.io/picard/command-line-overview.html#MergeSamFiles

bio/picard/mergesamfiles/test/Snakefile

@@ -11,6 +11,7 @@ rule merge_bams:
     # resource restrictions (https://snakemake.readthedocs.io/en/latest/snakefiles/rules.html#resources)
     # and which can be used to request RAM during cluster job submission as `{resources.mem_mb}`:
     # https://snakemake.readthedocs.io/en/latest/executing/cluster.html#job-properties
+    threads: 2
     resources:
         mem_mb=1024,
     wrapper:

bio/picard/mergesamfiles/wrapper.py

@@ -13,14 +13,24 @@
 extra = snakemake.params.get("extra", "")
 java_opts = get_java_opts(snakemake)
 
+if snakemake.threads == 1:
+    pass
+elif snakemake.threads == 2:
+    extra += " --USE_THREADING"
+else:
+    raise ValueError(
+        "Picard can use, at most, one extra thread for compression/decompression."
+    )
+
 inputs = " ".join("--INPUT {}".format(in_) for in_ in snakemake.input)
 log = snakemake.log_fmt_shell(stdout=False, stderr=True)
 
 with tempfile.TemporaryDirectory() as tmpdir:
     shell(
-        "picard  MergeSamFiles"
-        " {java_opts} {extra}"
+        "picard MergeSamFiles"
+        " {java_opts}"
         " {inputs}"
+        " {extra}"
         " --TMP_DIR {tmpdir}"
         " --OUTPUT {snakemake.output[0]}"
         " {log}"