draft: reference generation with templates

scripts/gen_output.sh

@@ -19,7 +19,7 @@ need_cmd anvil
 need_cmd chisel
 
 gen_help
-gen_cast
-gen_chisel
-gen_forge
-gen_vm
+# gen_cast
+# gen_chisel
+# gen_forge
+# gen_vm

scripts/gen_output/help.rs

@@ -26,8 +26,6 @@ const README: &str = r#"# CLI Reference
 
 <!-- Generated by scripts/gen_output/help.rs -->
 
-Automatically-generated CLI reference from `--help` output.
-
 {{#include ./SUMMARY.md}}
 "#;
 const TRIM_LINE_END_MARKDOWN: bool = false;
@@ -53,6 +51,10 @@ struct Args {
     #[arg(long, default_value = "2")]
     root_indentation: usize,
 
+    /// Template directory
+    #[arg(long)]
+    template_dir: PathBuf,
+
     /// Output directory
     #[arg(long)]
     out_dir: PathBuf,
@@ -94,6 +96,9 @@ fn main() -> io::Result<()> {
     let out_dir = args.out_dir;
     fs::create_dir_all(&out_dir)?;
 
+    let template_dir = args.template_dir;
+    fs::create_dir_all(&template_dir)?;
+
     let mut todo_iter: Vec<Cmd> = args
         .commands
         .iter()
@@ -124,7 +129,7 @@ fn main() -> io::Result<()> {
 
     // Generate markdown files.
     for (cmd, stdout) in &output {
-        cmd_markdown(&out_dir, cmd, stdout)?;
+        cmd_markdown(&out_dir, &template_dir, cmd, stdout)?;
     }
 
     // Generate SUMMARY.md.
@@ -217,8 +222,17 @@ fn parse_sub_commands(s: &str) -> Vec<String> {
 }
 
 /// Writes the markdown for a command to out_dir.
-fn cmd_markdown(out_dir: &Path, cmd: &Cmd, stdout: &str) -> io::Result<()> {
-    let out = format!("# {}\n\n{}", cmd, help_markdown(cmd, stdout));
+fn cmd_markdown(out_dir: &Path, template_dir: &Path, cmd: &Cmd, stdout: &str) -> io::Result<()> {
+    let mut out = format!("# {}\n\n{}", cmd, description_markdown(stdout));
+
+    let template_path = template_dir.join(cmd.md_path()).with_extension("md");
+    let template = fs::read_to_string(&template_path).unwrap_or_default();
+
+    if !template.is_empty() {
+        out.push_str(&content_markdown(&template));
+    }
+
+    out.push_str(&help_markdown(cmd, stdout));
 
     let out_path = out_dir.join(cmd.md_path());
     fs::create_dir_all(out_path.parent().unwrap())?;
@@ -227,11 +241,22 @@ fn cmd_markdown(out_dir: &Path, cmd: &Cmd, stdout: &str) -> io::Result<()> {
     Ok(())
 }
 
+/// Returns the markdown for a command's description.
+fn description_markdown(stdout: &str) -> String {
+    let (description, _) = parse_description(stdout);
+    format!("{description}\n\n")
+}
+
 /// Returns the markdown for a command's help output.
 fn help_markdown(cmd: &Cmd, stdout: &str) -> String {
-    let (description, s) = parse_description(stdout);
+    let (_, s) = parse_description(stdout);
     let help = preprocess_help(s.trim());
-    format!("{description}\n\n```bash\n$ {cmd} --help\n```\n\n```txt\n{help}\n```")
+    format!("### CLI\n\n```bash\n$ {cmd} --help\n```\n\n```txt\n{help}\n```")
+}
+
+/// Returns the markdown for the template content.
+fn content_markdown(content: &str) -> String {
+    format!("{content}\n")
 }
 
 /// Splits the help output into a description and the rest.

scripts/gen_output/help.sh

@@ -15,6 +15,7 @@ gen_help() {
     --root-indentation 4
     --readme
     --verbose
+    --template-dir "$SCRIPTS/templates/"
     --out-dir "$ROOT/src/reference/cli/"
     "${bins[@]}"
   )

scripts/templates/forge.md

@@ -0,0 +1,3 @@
+### Content
+
+Test

src/reference/cli/README.md

@@ -2,6 +2,4 @@
 
 <!-- Generated by scripts/gen_output/help.rs -->
 
-Automatically-generated CLI reference from `--help` output.
-
 {{#include ./SUMMARY.md}}