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

…se-quartodoc-for-docs

docs work

README.md

@@ -1,11 +1,69 @@
-# fave-recode
+# Getting started with `fave-recode`
+
 [![codecov](https://codecov.io/gh/Forced-Alignment-and-Vowel-Extraction/fave-recode/graph/badge.svg?token=C23B1H3DAX)](https://codecov.io/gh/Forced-Alignment-and-Vowel-Extraction/fave-recode)
-[![Maintainability](https://api.codeclimate.com/v1/badges/2375ddfef5d77ba1681d/maintainability)](https://codeclimate.com/github/Forced-Alignment-and-Vowel-Extraction/fave-recode/maintainability)
-[![FAVE Python CI](https://github.com/Forced-Alignment-and-Vowel-Extraction/fave-recode/actions/workflows/test-and-run.yml/badge.svg?branch=dev)](https://github.com/Forced-Alignment-and-Vowel-Extraction/fave-recode/actions/workflows/test-and-run.yml)
+[![Maintainability](https://api.codeclimate.com/v1/badges/2375ddfef5d77ba1681d/maintainability.png)](https://codeclimate.com/github/Forced-Alignment-and-Vowel-Extraction/fave-recode/maintainability)
+[![FAVE Python
+CI](https://github.com/Forced-Alignment-and-Vowel-Extraction/fave-recode/actions/workflows/test-and-run.yml/badge.svg?branch=dev)](https://github.com/Forced-Alignment-and-Vowel-Extraction/fave-recode/actions/workflows/test-and-run.yml)
+[![Build
+Docs](https://github.com/Forced-Alignment-and-Vowel-Extraction/fave-recode/actions/workflows/build-docs.yml/badge.svg)](https://forced-alignment-and-vowel-extraction.github.io/fave-recode/)
+
+The idea behind `fave-recode` is that no matter how much you may adjust
+the dictionary of a forced-aligner, you may still want to make
+programmatic changes to the output.
+
+## Installation
+
+You can install `fave-recode` at your system’s command line with `pip`.
+
+``` bash
+pip install fave-recode
+```
+
+## Basic usage
+
+Installation of the `fave-recode` python package makes the `fave_recode`
+executable, which can also be run at the command line. You can get help
+with `--help`
+
+``` bash
+fave_recode --help
+```
+
+    Usage: fave_recode [OPTIONS]
+
+    Inputs: [at least 1 required]
+      File inputs. Either a single file with -i or a path with -p. Not both.
+      -i, --input_file FILENAME  single input file
+      -p, --input_path PATH      Path to a set of files
+
+    Outputs:
+      -o, --output_file TEXT     An output file name
+      -d, --output_dest PATH     An output directory
+
+    Other options:
+      -s, --scheme TEXT          Recoding scheme. Built in options are cmu2labov
+                                 and cmu2phila  [required]
+      -r, --recode_stem TEXT     Stem to append to recoded TextGrid file names
+      -t, --target_tier TEXT     Target tier to recode
+      --help                     Show this message and exit.
+
+To recode a single file, you need to provide `fave_recode` with,
+minimally, the input file (the `-i` flag), and the recoding scheme (with
+the `-s` flag). There are a few default recoding schemes that come with
+`fave_recode`.
+
+``` bash
+ls data
+```
+
+    KY25A_1.TextGrid                 josef-fruehwald_speaker.TextGrid
 
-The goal is to separate vowel class recoding as a separate step from fave-extraction.
+``` bash
+fave_recode -i data/josef-fruehwald_speaker.TextGrid -s cmu2phila
 
-Planned framework
+ls data
+```
 
-- `praatio` for textgrid processing
-- `pyyaml` for defining the recoding
+    KY25A_1.TextGrid
+    josef-fruehwald_speaker.TextGrid
+    josef-fruehwald_speaker_recoded.TextGrid

README.qmd

@@ -0,0 +1,63 @@
+---
+title: Getting started with `fave-recode`
+engine: jupyter
+format: gfm
+---
+
+[![codecov](https://codecov.io/gh/Forced-Alignment-and-Vowel-Extraction/fave-recode/graph/badge.svg?token=C23B1H3DAX)](https://codecov.io/gh/Forced-Alignment-and-Vowel-Extraction/fave-recode)
+[![Maintainability](https://api.codeclimate.com/v1/badges/2375ddfef5d77ba1681d/maintainability)](https://codeclimate.com/github/Forced-Alignment-and-Vowel-Extraction/fave-recode/maintainability)
+[![FAVE Python CI](https://github.com/Forced-Alignment-and-Vowel-Extraction/fave-recode/actions/workflows/test-and-run.yml/badge.svg?branch=dev)](https://github.com/Forced-Alignment-and-Vowel-Extraction/fave-recode/actions/workflows/test-and-run.yml)
+[![Build Docs](https://github.com/Forced-Alignment-and-Vowel-Extraction/fave-recode/actions/workflows/build-docs.yml/badge.svg)](https://forced-alignment-and-vowel-extraction.github.io/fave-recode/)
+
+The idea behind `fave-recode` is that no matter how much you may adjust the dictionary of a forced-aligner, you may still want to make programmatic changes to the output.
+
+## Installation
+
+You can install `fave-recode` at your system's command line with `pip`.
+```bash
+pip install fave-recode
+```
+```{python}
+#| eval: false
+#| echo: false
+!pip install fave-recode
+```
+
+## Basic usage
+
+Installation of the `fave-recode` python package makes the `fave_recode` executable, which can also be run at the command line. You can get help with `--help`
+
+```bash
+fave_recode --help
+```
+```{python}
+#| filename: terminal
+#| echo: false
+!fave_recode --help
+```
+
+To recode a single file, you need to provide `fave_recode` with, minimally, the input file (the `-i` flag), and the recoding scheme (with the `-s` flag). There are a few default recoding schemes that come with `fave_recode`.
+
+```bash
+ls data
+```
+```{python}
+#| echo: false
+!ls docs/getting-started/data/
+```
+
+```bash
+fave_recode -i data/josef-fruehwald_speaker.TextGrid -s cmu2phila
+
+ls data
+```
+```{python}
+#| echo: false
+!fave_recode -i docs/getting-started/data/josef-fruehwald_speaker.TextGrid -s cmu2phila
+!ls docs/getting-started/data
+```
+
+```{python}
+#| echo: false
+!rm docs/getting-started/data/josef-fruehwald_speaker_recoded.TextGrid
+```

docs/_quarto.yml

@@ -2,9 +2,9 @@ project:
   type: website
   output-dir: _site
 
-
 website:
   page-navigation: true
+  image: assets/logo.png
   navbar:
     left:
       - file: getting-started/overview.qmd
@@ -15,31 +15,34 @@ website:
       - icon: github
         href: https://github.com/Forced-Alignment-and-Vowel-Extraction/fave-recode        
   sidebar:
-      - id: get-started
-        title: Get Started
-        style: floating
-        align: left
-        contents:
-          - getting-started/overview.qmd
-          - 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
+    - id: get-started
+      logo: assets/logo.png
+      collapse-level: 3
+      title: Get Started
+      style: floating
+      align: left
+      contents:
+        - getting-started/overview.qmd
+        - 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: 
     theme:
       light: flatly
       dark: darkly
+    toc: true
 
 # tell quarto to read the generated sidebar
 metadata-files:
@@ -71,4 +74,18 @@ quartodoc:
       contents:
         - rule_classes.Condition
         - rule_classes.Rule
-        - rule_classes.RuleSet
+        - rule_classes.RuleSet
+    - title: Relations
+    - subtitle: "`in`, `not in`"
+      contents:
+        - relations.in_relation
+        - relations.not_in_relation
+    - subtitle: "equals, not equals"
+      contents:
+        - relations.equals_relation
+        - relations.not_equals_relation
+    - subtitle: "Regex match"
+      contents:
+        - relations.rematches_relation
+        - relations.reunmatches_relation
+