docs: describe "typst-test watch" workaround with watchexec

second commit, without LSP formatting breadcrumbs

Author: swaits

README.md

@@ -10,8 +10,11 @@ Out of the box `typst-test` supports the following features:
 - provide extra scripting functionality
 - running custom scripts for test automation
 
+`typst-test` does not currently include a "watch" command to automatically run anytime a file changes.
+However, the book [includes a suggested workaround for this](https://tingerrr.github.io/typst-test/guides/watching.html).
+
 ## Stability
-`typst-test` currently makes no stability guarantees, it is considered pre-0.1.0, see the [Milestones] for it's progress towards a first release.
+`typst-test` currently makes no stability guarantees, it is considered pre-0.1.0, see the [Milestones] for its progress towards a first release.
 However, all PRs and pushes to main are tested in CI.
 A reasonably "stable" version of `typst-test` is available at the `ci-semi-stable` tag.
 This version is already used in the CI of various Typst packages, such as cetz, codly, valkyrie, hydra or subpar.

docs/book/src/README.md

@@ -20,6 +20,7 @@ This book contains a few sections aimed at answering the most common questions r
 After the quick start, a few guides delve deeper into some advanced topics.
 - [Writing Tests](./guides/tests.md) inspects adding, removing, updating and editing tests more closely.
 - [Using Test Sets](./guides/test-sets.md) delves into the test set language and how it can be used to isolate tests and speed up your TDD workflow.
+- [Watching for Changes](./guides/watching.md) automatically run tests while developing your package.
 - [Automation](./guides/automation.md) explains the ins and outs of hooks and how they can be used for testing typst preprocessors or formatters.
 - [Setting Up CI](./guides/ci.md) shows how to set up `typst-test` to continuously test all changes to your package.
 

docs/book/src/SUMMARY.md

@@ -8,6 +8,7 @@
 # Guides
 - [Writing Tests]()
 - [Using Test Sets](./guides/test-sets.md)
+- [Watching for Changes](./guides/watching.md)
 - [Automation]()
 - [Setting Up CI](./guides/ci.md)
 

docs/book/src/guides/watching.md

@@ -0,0 +1,28 @@
+# Watching for Changes
+
+`typst-test` does not currently support a "watch" command, which is common in this sort of tooling.
+This is due to some of the complexity in how it uses the core Typst libraries.
+
+However, you may workaround this by using [`watchexec`](https://watchexec.github.io/).
+To begin, install it following the installation instructions in its [README](https://github.com/watchexec/watchexec).
+
+Then, run a command like this in your package root directory, which is the same directory with your `typst.toml` and `README.md` file:
+
+```bash
+watchexec \
+  --watch . \
+  --clear \
+  --ignore 'tests/**/diff/**' \
+  --ignore 'tests/**/out/**' \
+  "typst-test r"
+```
+
+This will run `typst-test r` whenever any file changes other than those in your tests' `{diff,out}` directories.
+
+You may create an alias in your shell to make it more convenient:
+
+```bash
+alias ttw="watchexec --watch . --clear --ignore 'tests/**/diff/**' --ignore 'tests/**/out/**' 'typst-test r'"
+```
+
+Note, if your tests change any files in your package source tree, you may need to include them as additional `--ignore <glob>` patterns to the command.