Add docs for new 'rcl build' subcommand

Readme-driven development here, the command doesn't exist yet!

docs/rcl.md

@@ -6,6 +6,7 @@
 
 The `rcl` executable; see the commands for more details:
 
+ * [build](rcl_build.md)
  * [evaluate](rcl_evaluate.md)
  * [format](rcl_format.md)
  * [highlight](rcl_highlight.md)

docs/rcl_build.md

@@ -0,0 +1,25 @@
+# rcl build
+
+    rcl build [--] [<buildfile>]
+
+## Description
+
+The build command writes evaluated documents to files. It can be used to
+update many generated files in one command, similar to a build tool like Make
+or Ninja, but with the build targets specified in RCL rather than a Makefile.
+
+TODO: Link to a docs chapter like the Ninja one.
+
+When no file is specified, `rcl build` reads from `build.rcl` as the default.
+(This is unlike other <abbr>RCL</abbr> subcommands, which default to stdin.)
+When `<buildfile>` is `-`, read from stdin.
+
+## Build target schema
+
+TODO: Document.
+
+## Options
+
+### `--sandbox <mode>`
+
+See [`--sandbox` in `rcl evaluate`][rcl_evaluate.md#-sandbox-mode].

mkdocs.yml

@@ -39,6 +39,7 @@ nav:
       - "Python bindings": "python_bindings.md"
   - "Command reference":
       - "rcl": "rcl.md"
+      - "rcl build": "rcl_build.md"
       - "rcl evaluate": "rcl_evaluate.md"
       - "rcl format": "rcl_format.md"
       - "rcl highlight": "rcl_highlight.md"

src/cli.rs

@@ -22,6 +22,7 @@ Usage:
   rcl [<options>] <command> <arguments>
 
 Commands:
+  build        Write formatted evaluation results to files.
   evaluate     Evaluate a document to an output format.
   format       Auto-format an RCL document.
   highlight    Print a document with syntax highlighting.
@@ -49,6 +50,50 @@ Color modes:
   none    Do not color output at all.
 "#;
 
+const USAGE_BUILD: &str = r#"
+RCL -- A reasonable configuration language.
+
+Usage:
+  rcl [<options>] build [<buildfile>]
+
+The 'build' command writes evaluated documents to files. It can be used to
+update many generated files in one command, similar to a build tool like Make
+or Ninja, but with the build targets specified in RCL rather than a Makefile.
+The build file is itself an RCL document that should evaluate to a dict that
+maps target file paths to the contents and output format options for that file.
+
+Arguments:
+  <buildfile>       The file with build targets to process, or '-' for stdin.
+                    Defaults to 'build.rcl' when no file is specified.
+
+Options:
+  --sandbox <mode>  Sandboxing mode, see 'rcl evaluate --help` for an
+                    explanation of the modes. Defaults to 'workdir'.
+
+See also --help for global options.
+
+Build targets are dicts with these keys:
+  banner: Bool     For formats that support comments, whether to include a line
+                   that says the file was generated. Optional, default true.
+  contents: Any    The value to format and write to the output file.
+  format: String   The output format, must be one of the formats supported by
+                   'rcl evaluate --format', see 'rcl evaluate --help'.
+  width: Int       Target width for formatting, as for 'rcl evaluate --width'.
+                   Optional, defaults to 80.
+
+Example:
+  {
+    "alice.toml": {
+      contents = { name = "Alice", uid = 42 },
+      format = "toml",
+    },
+    "bob.toml": {
+      contents = { name = "Bob", uid = 43 },
+      format = "toml",
+    },
+  }
+"#;
+
 const USAGE_EVAL_QUERY: &str = r#"
 RCL -- A reasonable configuration language.
 
@@ -384,6 +429,7 @@ pub fn parse(args: Vec<String>) -> Result<(GlobalOptions, Cmd)> {
     }
 
     let help_opt = match cmd_help {
+        Some("build") => Some(Cmd::Help { usage: USAGE_BUILD }),
         Some("evaluate") => Some(Cmd::Help {
             usage: USAGE_EVAL_QUERY,
         }),