Add user manual (#250)

~~Blocked on #248~~

Adds the actual user manual mdBook, but doesn't build or publish it.

docs/.gitignore

@@ -0,0 +1 @@
+/book

docs/SUMMARY.md

@@ -0,0 +1,9 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Installation](./install.md)
+- [Getting started](./getting-started.md)
+- [Command-line arguments](./cli.md)
+- [Lifecycle hooks](./lifecycle-hooks.md)
+- [Comment evaluation](./comment-evaluation.md)
+- [Only load modules you need](./no-load.md)

docs/book.toml

@@ -0,0 +1,14 @@
+[book]
+authors = [
+    "Rebecca Turner",
+]
+language = "en"
+multilingual = false
+src = "."
+title = "ghciwatch"
+
+[output.html]
+curly-quotes = true
+git-repository-url = "https://github.com/MercuryTechnologies/ghciwatch"
+git-repository-icon = "fa-github"
+edit-url-template = "https://github.com/MercuryTechnologies/ghciwatch/edit/main/docs/{path}"

docs/cli.md

@@ -0,0 +1,366 @@
+# Command-line arguments for `ghciwatch`
+
+Ghciwatch loads a GHCi session for a Haskell project and reloads it
+when source files change.
+
+**Usage:** `ghciwatch [--command SHELL_COMMAND] [--watch PATH] [OPTIONS ...]`
+
+
+
+## Examples
+
+Load `cabal v2-repl` and watch for changes in `src`:
+
+    ghciwatch
+
+Load a custom GHCi session and watch for changes in multiple locations:
+
+    ghciwatch --command "cabal v2-repl lib:test-dev" \
+              --watch src --watch test
+
+Run tests after reloads:
+
+    ghciwatch --test-ghci TestMain.testMain \
+              --after-startup-ghci ':set args "--match=/OnlyRunSomeTests/"'
+
+Use `hpack` to regenerate `.cabal` files:
+
+    ghciwatch --before-startup-shell hpack \
+              --restart-glob '**/package.yaml'
+
+Also reload the session when `.persistentmodels` change:
+
+    ghciwatch --watch config/modelsFiles \
+              --reload-glob '**/*.persistentmodels'
+
+Don't reload for `README.md` files:
+
+    ghciwatch --reload-glob '!src/**/README.md'
+
+## Options
+<dl>
+
+<dt><a id="--command" href="#--command"><code>--command &lt;SHELL_COMMAND&gt;</code></a></dt><dd>
+
+A shell command which starts a `ghci` REPL, e.g. `ghci` or `cabal v2-repl` or similar.
+
+This is used to launch the underlying `ghci` session that `ghciwatch` controls.
+
+May contain quoted arguments which will be parsed in a `sh`-like manner.
+
+</dd>
+<dt><a id="--error-file" href="#--error-file"><code>--error-file &lt;ERROR_FILE&gt;</code></a></dt><dd>
+
+A file to write compilation errors to.
+
+The output format is compatible with `ghcid`'s `--outputfile` option.
+
+</dd>
+<dt><a id="--enable-eval" href="#--enable-eval"><code>--enable-eval</code></a></dt><dd>
+
+Evaluate Haskell code in comments.
+
+This parses line commands starting with `-- $>` or multiline commands delimited by `{- $>` and `<$ -}` and evaluates them after reloads.
+
+</dd>
+<dt><a id="--clear" href="#--clear"><code>--clear</code></a></dt><dd>
+
+Clear the screen before reloads and restarts
+
+</dd>
+<dt><a id="--no-interrupt-reloads" href="#--no-interrupt-reloads"><code>--no-interrupt-reloads</code></a></dt><dd>
+
+Don't interrupt reloads when files change.
+
+Depending on your workflow, `ghciwatch` may feel more responsive with this set.
+
+</dd>
+
+</dl>
+
+## Lifecycle hooks
+<dl>
+
+<dt><a id="--test-ghci" href="#--test-ghci"><code>--test-ghci &lt;GHCI_CMD&gt;</code></a></dt><dd>
+
+`ghci` commands to run tests
+
+Tests are run after startup and after reloads.
+
+Example: `TestMain.testMain`.
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--test-shell" href="#--test-shell"><code>--test-shell &lt;SHELL_CMD&gt;</code></a></dt><dd>
+
+Shell commands to run tests
+
+Tests are run after startup and after reloads.
+
+Commands starting with `async:` will be run in the background.
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--before-startup-shell" href="#--before-startup-shell"><code>--before-startup-shell &lt;SHELL_CMD&gt;</code></a></dt><dd>
+
+Shell commands to run before startup
+
+Startup hooks run when `ghci` is started (at `ghciwatch` startup and after `ghci` restarts).
+
+Commands starting with `async:` will be run in the background.
+
+This can be used to regenerate `.cabal` files with `hpack`.
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--after-startup-ghci" href="#--after-startup-ghci"><code>--after-startup-ghci &lt;GHCI_CMD&gt;</code></a></dt><dd>
+
+`ghci` commands to run after startup
+
+Startup hooks run when `ghci` is started (at `ghciwatch` startup and after `ghci` restarts).
+
+Use `:set args ...` to set command-line arguments for test hooks.
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--after-startup-shell" href="#--after-startup-shell"><code>--after-startup-shell &lt;SHELL_CMD&gt;</code></a></dt><dd>
+
+Shell commands to run after startup
+
+Startup hooks run when `ghci` is started (at `ghciwatch` startup and after `ghci` restarts).
+
+Commands starting with `async:` will be run in the background.
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--before-reload-ghci" href="#--before-reload-ghci"><code>--before-reload-ghci &lt;GHCI_CMD&gt;</code></a></dt><dd>
+
+`ghci` commands to run before reload
+
+Reload hooks are run when modules are changed on disk.
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--before-reload-shell" href="#--before-reload-shell"><code>--before-reload-shell &lt;SHELL_CMD&gt;</code></a></dt><dd>
+
+Shell commands to run before reload
+
+Reload hooks are run when modules are changed on disk.
+
+Commands starting with `async:` will be run in the background.
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--after-reload-ghci" href="#--after-reload-ghci"><code>--after-reload-ghci &lt;GHCI_CMD&gt;</code></a></dt><dd>
+
+`ghci` commands to run after reload
+
+Reload hooks are run when modules are changed on disk.
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--after-reload-shell" href="#--after-reload-shell"><code>--after-reload-shell &lt;SHELL_CMD&gt;</code></a></dt><dd>
+
+Shell commands to run after reload
+
+Reload hooks are run when modules are changed on disk.
+
+Commands starting with `async:` will be run in the background.
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--before-restart-ghci" href="#--before-restart-ghci"><code>--before-restart-ghci &lt;GHCI_CMD&gt;</code></a></dt><dd>
+
+`ghci` commands to run before restart
+
+Due to [a `ghci` bug][1], the `ghci` session must be restarted when Haskell modules
+are removed or renamed.
+
+[1]: https://gitlab.haskell.org/ghc/ghc/-/issues/11596
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--before-restart-shell" href="#--before-restart-shell"><code>--before-restart-shell &lt;SHELL_CMD&gt;</code></a></dt><dd>
+
+Shell commands to run before restart
+
+Due to [a `ghci` bug][1], the `ghci` session must be restarted when Haskell modules
+are removed or renamed.
+
+[1]: https://gitlab.haskell.org/ghc/ghc/-/issues/11596
+
+Commands starting with `async:` will be run in the background.
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--after-restart-ghci" href="#--after-restart-ghci"><code>--after-restart-ghci &lt;GHCI_CMD&gt;</code></a></dt><dd>
+
+`ghci` commands to run after restart
+
+Due to [a `ghci` bug][1], the `ghci` session must be restarted when Haskell modules
+are removed or renamed.
+
+[1]: https://gitlab.haskell.org/ghc/ghc/-/issues/11596
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--after-restart-shell" href="#--after-restart-shell"><code>--after-restart-shell &lt;SHELL_CMD&gt;</code></a></dt><dd>
+
+Shell commands to run after restart
+
+Due to [a `ghci` bug][1], the `ghci` session must be restarted when Haskell modules
+are removed or renamed.
+
+[1]: https://gitlab.haskell.org/ghc/ghc/-/issues/11596
+
+Commands starting with `async:` will be run in the background.
+
+Can be given multiple times.
+
+</dd>
+
+</dl>
+
+## File watching options
+<dl>
+
+<dt><a id="--poll" href="#--poll"><code>--poll &lt;DURATION&gt;</code></a></dt><dd>
+
+Use polling with the given interval rather than notification-based file watching.
+
+Polling tends to be more reliable and less performant. In particular, notification-based watching often misses updates on macOS.
+
+</dd>
+<dt><a id="--debounce" href="#--debounce"><code>--debounce &lt;DURATION&gt;</code></a></dt><dd>
+
+Debounce file events; wait this duration after receiving an event before attempting to reload.
+
+Defaults to 0.5 seconds.
+
+  Default value: `500ms`
+
+</dd>
+<dt><a id="--watch" href="#--watch"><code>--watch &lt;PATH&gt;</code></a></dt><dd>
+
+A path to watch for changes.
+
+Directories are watched recursively. Can be given multiple times.
+
+</dd>
+<dt><a id="--reload-glob" href="#--reload-glob"><code>--reload-glob &lt;RELOAD_GLOBS&gt;</code></a></dt><dd>
+
+Reload the `ghci` session when paths matching this glob change.
+
+By default, only changes to Haskell source files trigger reloads. If you'd like to exclude some files from that, you can add an ignore glob here, like `!src/my-special-dir/**/*.hs`.
+
+Globs provided here have precisely the same semantics as a single line in a `gitignore` file (`man gitignore`), where the meaning of `!` is inverted: namely, `!` at the beginning of a glob will ignore a file.
+
+The last matching glob will determine if a reload is triggered.
+
+Can be given multiple times.
+
+</dd>
+<dt><a id="--restart-glob" href="#--restart-glob"><code>--restart-glob &lt;RESTART_GLOBS&gt;</code></a></dt><dd>
+
+Restart the `ghci` session when paths matching this glob change.
+
+By default, only changes to `.cabal` or `.ghci` files or Haskell source files being moved/removed will trigger restarts.
+
+Due to [a `ghci` bug][1], the `ghci` session must be restarted when Haskell modules are removed or renamed.
+
+See `--reload-globs` for more details.
+
+Can be given multiple times.
+
+[1]: https://gitlab.haskell.org/ghc/ghc/-/issues/11596
+
+</dd>
+
+</dl>
+
+## Logging options
+<dl>
+
+<dt><a id="--log-filter" href="#--log-filter"><code>--log-filter &lt;LOG_FILTER&gt;</code></a></dt><dd>
+
+Log message filter.
+
+Can be any of "error", "warn", "info", "debug", or "trace". Supports more granular filtering, as well.
+
+The grammar is: `target[span{field=value}]=level`, where `target` is a module path, `span` is a span name, and `level` is one of the levels listed above.
+
+See [documentation in `tracing-subscriber`][1].
+
+A nice value is `ghciwatch=debug`.
+
+[1]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html
+
+  Default value: `ghciwatch=info`
+
+</dd>
+<dt><a id="--backtrace" href="#--backtrace"><code>--backtrace &lt;BACKTRACE&gt;</code></a></dt><dd>
+
+How to display backtraces in error messages
+
+  Default value: `0`
+
+  Possible values:
+  - `0`:
+    Hide backtraces in errors
+  - `1`:
+    Display backtraces in errors
+  - `full`:
+    Display backtraces with all stack frames in errors
+
+
+</dd>
+<dt><a id="--trace-spans" href="#--trace-spans"><code>--trace-spans &lt;TRACE_SPANS&gt;</code></a></dt><dd>
+
+When to log span events, which loosely correspond to tasks being run in the async runtime.
+
+Allows multiple values, comma-separated.
+
+  Default value: `new,close`
+
+  Possible values:
+  - `new`:
+    Log when spans are created
+  - `enter`:
+    Log when spans are entered
+  - `exit`:
+    Log when spans are exited
+  - `close`:
+    Log when spans are dropped
+  - `none`:
+    Do not log span events
+  - `active`:
+    Log when spans are entered/exited
+  - `full`:
+    Log all span events
+
+
+</dd>
+<dt><a id="--log-json" href="#--log-json"><code>--log-json &lt;PATH&gt;</code></a></dt><dd>
+
+Path to write JSON logs to.
+
+JSON logs are not yet stable and the format may change on any release.
+
+</dd>
+
+</dl>
+
+
+