squash

book/plugins/tutorials/add-usage-examples.md

@@ -1,13 +1,73 @@
 (add-nw-align-usage)=
 # Add usage examples
 
-Your new functionality isn't *really* done until you document it, so let's do that now.
+If you want others to use your new functionality, it isn't *really* done until you document it.
+Let's do that now.
 This will ensure that users know how to use your code, and will give them something to try after they install your plugin to convince them that it's working.
 I generally find that I'm the first person to benefit from my documentation, and in some cases I'm also the person who most frequently benefits from my documentation (e.g., if it's code that I write for my own purposes, rather than something I intend to broadly disseminate).
 
-QIIME 2 provides a framework for defining `UsageExamples` for plugins.
+QIIME 2 provides a framework for defining usage examples for plugins.
 These are defined abstractly, and the QIIME 2 framework knows how to translate those abstract definitions into usage examples for different interfaces (the {term}`Python 3 API`, {term}`q2cli`, and {term}`Galaxy`, as of this writing).
 So, by writing a single usage example, your documentatation is targeted toward users with different levels of computational expertise.
 This is one way the framework supports our goal of meeting users where they are in terms of their computational experience, and it's one of the big benefits that you as a plugin developer gets by developing with QIIME 2.
 
-**This section is incomplete.**
+**This section is incomplete.**
+## Defining a usage example for `nw-align`
+
+## Displaying usage examples
+
+### Command line interface
+
+```shell
+qiime dwq2 nw-align --help
+Usage: qiime dwq2 nw-align [OPTIONS]
+
+...
+
+Examples:
+  # ### example: Align two DNA sequences.
+  qiime dwq2 nw-align \
+    --i-seq1 seq1.qza \
+    --i-seq2 seq2.qza \
+    --o-aligned-sequences msa.qza
+```
+
+```shell
+$ qiime dwq2 nw-align --example-data usage-example-data/
+```
+
+### Python 3 API
+
+```python
+from qiime2.plugins import dwq2, ArtifactAPIUsage
+
+examples = dwq2.actions.nw_align.examples
+
+for example in examples.values():
+    use = ArtifactAPIUsage()
+    example(use)
+    print(use.render())
+```
+
+Will display the following:
+
+```python
+import qiime2.plugins.dwq2.actions as dwq2_actions
+
+msa, = dwq2_actions.nw_align(
+    seq1=seq1,
+    seq2=seq2,
+)
+```
+
+## Optional exercise
+
+Add a usage example for your `summarize` visualizer.
+
+Need some hints?
+
+```{toggle}
+For your example data, you can use the output generated by the `nw-align` usage example that we created here.
+If you export that artifact, you can find the data in the format you'll need to create it in your factory function.
+You can also find the artifact class that you'll need to use in your `qiime2.Artifact.import_data` call using the `qiime tools peek` command.
+```