Merge pull request #47 from Forced-Alignment-and-Vowel-Extraction/8-u…

…se-quartodoc-for-docs

8 use quartodoc for docs

docs/_quarto.yml

@@ -24,6 +24,16 @@ website:
           - section: Processing patterns
             contents: 
               - getting-started/single-file.qmd
+              - getting-started/directory.qmd
+          - section: Customizing a recoding scheme
+            contents:
+              - getting-started/rule-scheme-basics.qmd
+              - getting-started/rule-application.qmd
+              - section: Details
+                contents:
+                  - getting-started/condition-attributes.qmd
+                  - getting-started/condition-relations.qmd
+
 
 format:
   html: 

docs/getting-started/condition-attributes.qmd

@@ -0,0 +1,5 @@
+---
+title: Condition Attributes
+engine: jupyter
+toc: true
+---

docs/getting-started/condition-relations.qmd

@@ -0,0 +1,5 @@
+---
+title: Condition Relations
+engine: jupyter
+toc: true
+---

docs/getting-started/directory.qmd

@@ -0,0 +1,132 @@
+---
+title: Processing a directory
+engine: jupyter
+toc: true
+---
+
+```{python}
+#| echo: false
+from pathlib import Path
+```
+
+There are a few different ways you can process a directory of TextGrid files
+
+## Only an input path and scheme provided
+
+You can point `fave_recode` at an entire directory and just specify a recoding scheme.
+
+::: {.callout-note}
+## This will happen:
+`fave_recode` will save each recoded TextGrid to same input directory `_recoded` added to the end of the filename.
+:::
+
+
+::: {.callout-warning}
+## If there is already a file in the output location:
+If there is already a file in the output location, `fave_recode` will ask you whether or not you want to overwrite it. It will do this for *every* already existing file.
+:::
+
+### Example
+
+```bash
+ls data
+```
+
+```{python}
+#| echo: false
+!ls data
+```
+
+```bash
+fave_recode -p data -s cmu2labov
+ls data
+```
+
+```{python}
+!fave_recode -p data -s cmu2labov
+!ls data
+```
+
+```{python}
+#| echo: false
+p = Path("data")
+f = list(p.glob("*_recoded.TextGrid"))
+_ = [x.unlink() for x in f]
+```
+
+## Providing a recode stem
+You can provide `fave_recode` with a different recode stem to append to the original filenames with the `-r` flag.
+
+::: {.callout-note}
+## This will happen:
+`fave_recode` will save each recoded TextGrid to the same directory as the originals with the string you provided added to the end of the filename.
+:::
+
+### Example
+
+```bash
+ls data
+```
+
+```{python}
+#| echo: false
+!ls data
+```
+
+```bash
+fave_recode -p data -s cmu2labov -r _labovcode
+ls data
+```
+
+```{python}
+!fave_recode -p data -s cmu2labov -r _labovcode
+!ls data
+```
+
+```{python}
+#| echo: false
+p = Path("data")
+f = list(p.glob("*_labovcode.TextGrid"))
+_ = [x.unlink() for x in f]
+```
+
+## Providing an output directory
+You can also provide `fave_recode` with an output directory with `-d`. 
+
+::: {.callout-note}
+## This will happen:
+`fave_recode` will save each recoded TextGrid to the output directory with the recode string appended to the end of the original filenames.
+:::
+
+::: {.callout-warning}
+## If there is already a file in the output location:
+If there is already a file in the output location, `fave_recode` will ask you whether or not you want to overwrite it. It will do this for each file.
+:::
+
+::: {.callout-warning}
+## If there the output directory doesn't exist:
+If the output directory doesn't exist, `fave_recode` will ask you whether or not you want to create it.
+:::
+
+### Example
+```{python}
+#| echo: false
+o = Path("output")
+if not o.is_dir():
+    o.mkdir()
+```
+
+```bash
+fave_recode -p data -s cmu2labov -d output
+ls output
+```
+```{python}
+#| echo: false
+!fave_recode -p data -s cmu2labov -d output
+!ls output
+```
+```{python}
+#| echo: false
+f = list(o.glob("*TextGrid"))
+_ = [x.unlink() for x in f]
+```

docs/getting-started/resources/just-schwa.yml

@@ -0,0 +1,6 @@
+- rule: schwa
+  conditions:
+    - attribute: label
+      relation: ==
+      set: AH0
+  return: "@"

docs/getting-started/rule-application.qmd

@@ -0,0 +1,37 @@
+---
+title: Rule application
+engine: jupyter
+toc: true
+---
+
+## Single Rule Application
+
+A single rule will only apply if **all** of its conditions return `true`.
+
+## Ruleset Application
+
+Rules in a ruleset are applied in sequence, and once a rule applies to an interval, no other rules can apply. 
+
+:::{.callout-important}
+This means you *must* place more specific rules towards the top of your ruleset.
+:::
+
+For example, if you wanted every word with `AE1` followed by `N` to go into one category, *unless* it's the word `ran`, you would need to place the rule about `ran` into its own rule *before* the more general rule.
+
+```yaml
+- rule: ran-rule
+  conditions:
+    - attribute: inword.label
+      relation: ==
+      set: ran
+  return: ae1
+- rule: aen-rule 
+  conditions:
+    - attribute: label
+      relation: ==
+      set: AE1
+    - attribute: fol.label
+      relation: ==
+      set: 'N'  
+  return: ae2
+```

docs/getting-started/rule-scheme-basics.qmd

@@ -0,0 +1,51 @@
+---
+title: Rule basics
+engine: jupyter
+toc: true
+---
+
+Recoding rule schemes can be written in a yaml file. A very simple rule scheme would be to recode the CMU dictionary label `AH0` to a schwa-like character, `@`. Here's the contents of a `just-schwa.yml` file.
+
+```yaml
+# just-schwa.yml
+- rule: schwa
+  conditions:
+    - attribute: label
+      relation: ==
+      set: AH0
+  return: "@"
+```
+
+## Anatomy of a rule scheme
+
+Every rule scheme file is a list of rules, which indicated by each line starting a new rule beginning with `-`.
+
+```yaml
+# rule skeleton
+- rule: ...
+  ...
+- rule: ...
+  ...
+```
+
+### The Rule Name
+Each rule has a rule name, which is indicated by the text following `rule:`. 
+
+### The Rule Conditions
+Each rule also has a list of conditions which can result in `true` or a `false`. The `schwa` rule has just one condition.
+
+```yaml
+attribute: label
+relation: ==
+set: AH0
+```
+
+- `attribute` refers to properties of a TextGrid interval. [Read more here](condition-attributes.qmd).
+- `relation` refers to how the specified `attribute` relates to the `set`. [Read more here](condition-relations.qmd).
+- `set` is some reference value or set of values.
+
+This condition will return `true` with a TextGrid interval's `label` is equal to (`==`) the string `AH0`.
+
+### The Rule Outcome
+
+The label of a TextGrid interval is replaced with the value in `return`.