Library tutorial extension syntax

[thermokarst]

The following is a first-draft mockup of a potential interface-less QIIME 2 tutorial template format. The idea is to write once (in markdown), and render out the outputs (via execution), as well as a handful of interfaces.

---

# Demultiplexing and Trimming Adapters from Reads with q2-cutadapt

Multiplexed reads with the barcodes in the sequence reads can be
demultiplexed in QIIME 2 using the `q2-cutadapt` plugin, which wraps the
[`cutadapt`](https://cutadapt.readthedocs.io) tool. (Multiplexed sequences
prepared with the EMP protocol, where barcode reads are in a separate file,
as always can be demultiplexed with the `q2-demux` plugin.) The following
tutorial utilizes a toy dataset to illustrate some of the methods in
`q2-cutadapt`.

# Download and import data used in this tutorial

% the `forward.fastq.gz` and `metadata.tsv` files will be stored under
% the `data/` dir, which will be the extent of the data scope. Everything
% stored in `data/` will get download blocks generated automatically.

    ```usage:register-factories
    def data_factory():
        return Artifact.import_data('MultiplexedSingleEndBarcodeInSequence',
                                    'forward.fastq.gz')

    def metadata_factory():
        return Metadata.load('data/metadata.tsv')

% the usage:initialize-data directive is non-rendering, it is intended % for registration and setup of the example.

```usage:initialize-data
data = use.init_data('data', data_factory)
metadata = use.init_metadata('metadata', metadata_factory)
```

The data here consists of single-end reads (6 reads total). There are two samples present in the data, with the following barcodes on the 5' end:

```usage:render-metadata data/metadata.tsv
```

Demultiplex the reads

Now that we have everything imported, let's do the thing:

```usage
barcodes_col = use.get_metadata_column('barcodes', metadata)

use.action(
    UsageAction(
        plugin_id='cutadapt',
        action_id='demux_single',
    ),
    UsageInputs(
        seqs=data,
        error_rate=0,
        barcodes=barcodes_col,
    ),
    UsageOutputNames(
        per_sample_sequences='demultiplexed_seqs',
        untrimmed_sequences='untrimmed',
    )
)
```

As you can see - the reads are now demuxed. Enjoy!

[thermokarst]

% the `usage:initialize-data` directive is non-rendering, it is intended
% for registration and setup of the example.

    ```usage:initialize-data
    data = use.init_data('data', data_factory)
    metadata = use.init_metadata('metadata', metadata_factory)

This might not be necessary- we might be able to just include the init-data in a bare usage block.

[ebolyen]

What if instead of being "non-rendering", it generated a "download" element like we have in the tutorials?

[ebolyen]

For usage:render-metadata what if it was a direct analogy to inspect-metadata? And there was some complex element which would summarize but also show you the entire metadata if you clicked about in it.

[thermokarst]

What if instead of being "non-rendering", it generated a "download" element like we have in the tutorials?

I like it, and I think that is currently register-factories behavior.

For usage:render-metadata what if it was a direct analogy to inspect-metadata? And there was some complex element which would summarize but also show you the entire metadata if you clicked about in it.

Yep, that sounds perfect, I was kinda thinking something like the tabulate viz.