Documentation on RachisWarning

book/plugins/how-to-guides/create-register-transformer.md

@@ -4,7 +4,7 @@
 Transformers are often short Python functions that convert one file format or data type to another file format or data type.
 These functions are never directly called by users or developers, so by convention they don't get informative function names (as the annotations of the input and output provide complete detail on what they do).
 
-Here's are two example `transformer` that are [defined and registered in `q2-types`](https://github.com/qiime2/q2-types/blob/e25f9355958755343977e037bbe39110cfb56a63/q2_types/distance_matrix/_transformer.py#L16):
+Here are two example `transformer` that are [defined and registered in `q2-types`](https://github.com/qiime2/q2-types/blob/e25f9355958755343977e037bbe39110cfb56a63/q2_types/distance_matrix/_transformer.py#L16):
 
 ```python
 import skbio

book/plugins/how-to-guides/raise-visible-warning.md

@@ -0,0 +1,28 @@
+(howto-raise-visible-warning)=
+# Raising a Visible Warning
+
+Warnings raised by the Python `warning` library are suppressed by the QIIME2 framework by defualt. In order to make sure the warnings raised by your plugin are visible on the command line you must use the `RachisWarning` subclass. This class can be imported from the QIIME2 framework, specifically from `qiime2.core.exceptions`. Below is an excerpt from a [QIIME2 plugin registered in `q2-feature-table` importing and raising a `RachisWarning`.](https://github.com/qiime2/q2-feature-table/blob/b6a312e612338db0f69c97641372e7f0005b43f5/q2_feature_table/_merge.py#L90C12-L93C14)
+
+```python
+from qiime2.core.excpetions import RachisWarnings
+
+def merge_taxa(data: pd.DataFrame) -> pd.DataFrame:
+    if len(data) > 1:
+        depths = []
+        for taxonomy in data:
+            max = 0
+            for _, row in taxonomy.iterrows():
+                depth = row['Taxon'].count(';')
+                if depth > max:
+                    max = depth
+
+            depths.append(max)
+        if len(set(depths)) != 1:
+            warnings.warn(
+                "You are merging taxonomies with different depths.",
+                RachisWarning
+            )
+```
+This plugin has a `RachisWarning` raised when the taxonomies have different depths. Since the `RachisWarning` is a subclass of `UserWarning` from the
+built in Python `warnings` library, on which you can find more in depth documentation [here,](https://docs.python.org/3/library/warnings.html) they behave
+completely the same outside of command line visibility.