[docs/commands] Add CLI Documentation

docs/commands/draw/braille.md

@@ -0,0 +1,43 @@
+---
+title: "picharsso draw braille - CLI - Picharsso"
+description: "Use the Braille style."
+---
+
+# `picharsso draw braille`
+
+*Use the [Braille style](/styles/braille/).*
+
+--8<-- "docs/snippets/chunks/draw/styles/braille/example.md"
+
+## Usage
+
+```bash
+picharsso draw braille [options]
+```
+
+## Options
+
+### `-t`, `--threshold` `INTEGER` `RANGE`
+:   *Threshold pixel luminance (from grayscale). [default: 64]*
+
+    ??? example
+        Consider the following image:
+
+        --8<-- "docs/snippets/embed/subjects/contributions.html"
+
+        ```bash
+        picharsso draw -c -H 32 docs/assets/images/subjects/contributions.webp braille -t <threshold>
+        ```
+
+        Here's what it should look like:
+        
+        --8<-- "docs/snippets/chunks/draw/styles/braille/threshold.md"
+
+
+### `-h`, `--help`
+:   *Show this message and exit.*
+
+    ??? abstract "Message"
+        ```
+        --8<-- "docs/snippets/cli/draw/braille/help.txt"
+        ```

docs/commands/draw/gradient.md

@@ -0,0 +1,58 @@
+---
+title: "picharsso draw gradient - CLI - Picharsso"
+description: "Use the gradient style."
+---
+
+# `picharsso draw gradient`
+
+*Use the [gradient style](/styles/gradient/).*
+
+--8<-- "docs/snippets/chunks/draw/styles/gradient/example.md"
+
+## Usage
+
+```bash
+picharsso draw gradient [options]
+```
+
+## Options:
+
+###  `-s`, `--charset` `TEXT`
+:   *Character set ordered by increasing 'brightness'. [default:  :!?PG@]*
+
+    ??? example
+        Consider the following image:
+
+        --8<-- "docs/snippets/embed/subjects/slack.html"
+
+        ```bash
+        picharsso draw -c -H 32 docs/assets/images/subjects/slack.webp gradient -s <charset>
+        ```
+
+        Here's what it should look like:
+
+        --8<-- "docs/snippets/chunks/draw/styles/gradient/charset.md"
+
+###  `-n`, `--negative`
+:   Whether to invert output text brightness.
+
+    ??? example
+        Consider the following image:
+
+        --8<-- "docs/snippets/embed/subjects/github.html"
+
+        ```bash
+        picharsso draw -H 32 docs/assets/images/subjects/github.webp gradient [-n]
+        ```
+
+        Here's what it should look like:
+
+        --8<-- "docs/snippets/chunks/draw/styles/gradient/negative.md"
+
+###  `-h`, `--help`
+:   *Show this message and exit.*
+
+    ??? abstract "Message"
+        ```
+        --8<-- "docs/snippets/cli/draw/gradient/help.txt"
+        ```

docs/commands/draw/index.md

@@ -0,0 +1,159 @@
+---
+title: "picharsso draw - CLI - Picharsso"
+description: "Generate text art from an image."
+---
+
+# `picharsso draw`
+
+*Generate text art from an image.*
+
+## Usage
+
+```
+picharsso draw [options] <path> <command> [args]
+```
+
+## Arguments
+
+### `<path>`
+:   *Path to the image file.*
+
+## Options
+
+### `-c`, `--colorize`
+:   *Apply image colors to output text.*
+
+    ??? example
+        Consider the following image:
+
+        --8<-- "docs/snippets/embed/subjects/instagram.html"
+
+        ```bash
+        picharsso draw [-c] -H 32 docs/assets/images/subjects/instagram.webp gradient
+        ```
+
+        Here's what it should look like:
+
+        --8<-- "docs/snippets/chunks/format/colorize.md"
+
+### `-m`, `--mode` [`ansi`|`html`]
+:   *Format mode for output text.  [default: ansi]*
+
+    --8<-- "docs/snippets/references/formats.md"
+
+### `-r`, `--resample` [`nearest`|`box`|`bilinear`|`hamming`|`bicubic`|`lanczos`]
+:   *Resampling filter.  [default: nearest]*
+
+    ??? example
+        Consider the following image:
+
+        --8<-- "docs/snippets/embed/subjects/starry-night.html"
+
+        ```bash
+        picharsso draw -c -term-h -r <resample> docs/assets/images/subjects/starry-night.webp gradient -s "█"
+        ```
+
+        Here's what it should look like:
+
+        --8<-- "docs/snippets/chunks/draw/resample.md"
+
+### `-H`, `--height` `INTEGER`
+:   *Height of output text in characters.*
+    *If 0, derives from width.  [default: 0]*
+
+    !!! info "Lines"
+        `height` is the number of lines in the text output.
+
+    ??? example
+        Consider the following image:
+        
+        --8<-- "docs/snippets/embed/subjects/zima.html"
+        
+        ```bash
+        picharsso draw -c -H 32 docs/assets/images/subjects/zima.webp gradient
+        ```
+
+        Here's what it should look like:
+
+        --8<-- "docs/snippets/embed/outputs/draw/dimensions/zima-h32.html"
+
+### `-W`, `--width` `INTEGER`
+:   *Width of output text in characters.*
+    *If 0, derives from height.  [default: 0]*
+
+    !!! info "Characters per line"
+        `width` is the number of characters (including whitespace) per line in the text output.
+
+    ??? example
+        Consider the following image:
+        
+        --8<-- "docs/snippets/embed/subjects/zima.html"
+
+        ```bash
+        picharsso draw -c -W 32 docs/assets/images/subjects/zima.webp gradient
+        ```
+
+        Here's what it should look like:
+
+        --8<-- "docs/snippets/embed/outputs/draw/dimensions/zima-w32.html"
+
+### `-term-h`, `--terminal-height`
+:   *Sets height to terminal height.*
+
+    ??? example
+        Consider the following image:
+        
+        --8<-- "docs/snippets/embed/subjects/zima.html"
+
+        ```bash
+        picharsso draw -c -term-h docs/assets/images/subjects/zima.webp gradient
+        ```
+
+        Here's what it should look like:
+
+        --8<-- "docs/snippets/embed/outputs/draw/dimensions/zima-term-h.html"
+
+    ??? bug
+        When used while [piping](https://en.wikipedia.org/wiki/Pipeline_(Unix)),
+        `height` is set to the default terminal height,
+        which is usually `24`.
+      
+### `-term-w`, `--terminal-width`
+:   *Sets width to terminal width.*
+
+    ??? example
+        Consider the following image:
+        
+        --8<-- "docs/snippets/embed/subjects/zima.html"
+
+        ```bash
+        picharsso draw -c -term-w docs/assets/images/subjects/zima.webp gradient
+        ```
+
+        Here's what it should look like:
+
+        --8<-- "docs/snippets/embed/outputs/draw/dimensions/zima-term-w.html"
+
+    ??? bug
+        When used while [piping](https://en.wikipedia.org/wiki/Pipeline_(Unix)),
+        `width` is set to the default terminal width,
+        which is usually `80`.
+
+### `-h`, `--help`
+:   *Show this message and exit.*
+
+    ??? abstract "Message"
+        ```
+        --8<-- "docs/snippets/cli/draw/help.txt"
+        ```
+
+## Subcommands
+
+--8<-- "docs/snippets/references/styles.md"
+
+### [`braille`](/commands/draw/braille/)
+:   Use the [Braille style](/styles/braille/).
+
+### [`gradient`](/commands/draw/gradient/)
+:   Use the [gradient style](/styles/gradient/).
+

docs/commands/index.md

@@ -0,0 +1,32 @@
+---
+title: "picharsso - CLI - Picharsso"
+description: "A utility for converting images to text art."
+---
+
+# `picharsso`
+
+*A utility for converting images to text art.*
+
+## Usage
+
+```bash
+picharsso [options] <command> [args]
+```
+
+## Options
+
+### `-h`, `--help`
+:   *Show this message and exit.*
+
+    ??? abstract "Message"
+        ```
+        --8<-- "docs/snippets/cli/help.txt"
+        ```
+
+## Subcommands
+
+### [`draw`](/commands/draw/)
+:   *Generate text art from an image.*
+
+### [`info`](/commands/info/)
+:   *Displays package information.*

docs/commands/info.md

@@ -0,0 +1,25 @@
+---
+title: "picharsso info - CLI - Picharsso"
+description: "Displays package information."
+---
+
+# `picharsso info`
+
+*Displays package information.*
+
+## Usage
+
+```bash
+picharsso info [options]
+```
+
+## Options
+
+### `-h`, `--help`
+:   *Show this message and exit.*
+
+    ??? abstract "Message"
+        ```
+        --8<-- "docs/snippets/cli/info/help.txt"
+        ```
+        

docs/snippets/chunks/draw/resample.md

@@ -0,0 +1,17 @@
+=== "resample = 'nearest'"
+    --8<-- "docs/snippets/embed/outputs/draw/resample/starry-night-resample-nearest.html"
+
+=== "'box'"
+    --8<-- "docs/snippets/embed/outputs/draw/resample/starry-night-resample-box.html"
+
+=== "'bilinear'"
+    --8<-- "docs/snippets/embed/outputs/draw/resample/starry-night-resample-bilinear.html"
+
+=== "'hamming'"
+    --8<-- "docs/snippets/embed/outputs/draw/resample/starry-night-resample-hamming.html"
+
+=== "'bicubic'"
+    --8<-- "docs/snippets/embed/outputs/draw/resample/starry-night-resample-bicubic.html"
+
+=== "'lanczos'"
+    --8<-- "docs/snippets/embed/outputs/draw/resample/starry-night-resample-lanczos.html"

docs/snippets/chunks/draw/styles/braille/threshold.md

@@ -0,0 +1,14 @@
+=== "threshold = 0"
+    --8<-- "docs/snippets/embed/outputs/draw/styles/braille/threshold/contributions-braille-t0.html"
+
+=== "70"
+    --8<-- "docs/snippets/embed/outputs/draw/styles/braille/threshold/contributions-braille-t70.html"
+
+=== "108"
+    --8<-- "docs/snippets/embed/outputs/draw/styles/braille/threshold/contributions-braille-t108.html"
+
+=== "168"
+    --8<-- "docs/snippets/embed/outputs/draw/styles/braille/threshold/contributions-braille-t168.html"
+
+=== "210"
+    --8<-- "docs/snippets/embed/outputs/draw/styles/braille/threshold/contributions-braille-t210.html"

docs/snippets/chunks/draw/styles/gradient/charset.md

@@ -0,0 +1,11 @@
+=== "charset = ' :!?PG@' (default)"
+    --8<-- "docs/snippets/embed/outputs/draw/styles/gradient/charset/slack-gradient-charset-default.html"
+
+=== "'.'"
+    --8<-- "docs/snippets/embed/outputs/draw/styles/gradient/charset/slack-gradient-charset-dot.html"
+
+=== "'#'"
+    --8<-- "docs/snippets/embed/outputs/draw/styles/gradient/charset/slack-gradient-charset-hash.html"
+
+=== "'█'"
+    --8<-- "docs/snippets/embed/outputs/draw/styles/gradient/charset/slack-gradient-charset-block.html"

docs/snippets/chunks/draw/styles/gradient/negative.md

@@ -0,0 +1,5 @@
+=== "negative = False"
+    --8<-- "docs/snippets/embed/outputs/draw/styles/gradient/negative/github-gradient-normal.html"
+
+=== "True"
+    --8<-- "docs/snippets/embed/outputs/draw/styles/gradient/negative/github-gradient-negative.html"

docs/snippets/chunks/format/colorize.md

@@ -0,0 +1,5 @@
+=== "colorize = False"
+    --8<-- "docs/snippets/embed/outputs/format/colorize/instagram-gray.html"
+
+=== "True"
+    --8<-- "docs/snippets/embed/outputs/format/colorize/instagram-color.html"

docs/snippets/cli/draw/braille/help.txt

@@ -0,0 +1,9 @@
+Usage: picharsso draw braille [options]
+
+  Use the Braille style.
+
+Options:
+  -t, --threshold INTEGER RANGE  Threshold pixel luminance (from grayscale).
+                                 [default: 64]
+
+  -h, --help                     Show this message and exit.