Merge branch 'rh/docs_columns_arg' into 'master'

added warning about positional arguments and --columns

See merge request minknow/pod5-file-format!308

Author: 0x55555555

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Transfers dataframes used in subsetting / filter use categorical fields to reduce memory consumption
 - Polars version increased to `~=0.19`
+- Documentation regarding positional arguments
 - Renamed deprecated `polars.groupby` to `polars.group_by`
 
 ### Fixed

docs/docs/tools.rst

@@ -239,7 +239,7 @@ then ``pod5 filter`` might be a more appropriate tool as the only input is a lis
     $ pod5 subset example_1.pod5 --csv mapping.csv
 
     # Subset input(s) using a dynamic mapping created at runtime
-    $ pod5 subset example_1.pod5 --table table.txt --columns barcode
+    $ pod5 subset example_1.pod5 --columns barcode --table table.txt
 
 .. important::
 
@@ -248,6 +248,18 @@ then ``pod5 filter`` might be a more appropriate tool as the only input is a lis
     will be raised unless the ``--duplicate-ok`` argument is set. If ``--duplicate-ok`` is
     set then both reads will be written to the output, although this is not recommended.
 
+.. warning::
+
+    The ``--columns`` argument will greedily consume values and as such, care should be taken
+    with the placement of any positional arguments. The following line will result in an error
+    as the input pod5 file is consumed by ``--columns`` resulting in no input file being set.
+
+    .. code-block:: console
+
+        # Invalid placement of positional argument example.pod5
+        $ pod5 subset --table table.txt --columns barcode example.pod5
+
+
 Creating a Subset Mapping
 ------------------------------
 

python/pod5/README.md

@@ -340,6 +340,17 @@ then ``pod5 filter`` might be a more appropriate tool as the only input is a lis
 > will be raised unless the ``--duplicate-ok`` argument is set. If ``--duplicate-ok`` is
 > set then both reads will be written to the output, although this is not recommended.
 
+#### Note on positional arguments
+
+> The ``--columns`` argument will greedily consume values and as such, care should be taken
+> with the placement of any positional arguments. The following line will result in an error
+> as the input pod5 file is consumed by ``--columns`` resulting in no input file being set.
+
+```bash
+# Invalid placement of positional argument example.pod5
+$ pod5 subset --table table.txt --columns barcode example.pod5
+```
+
 #### Creating a Subset Mapping
 
 ##### Target Mapping (.csv)