feat: generate library documentation from bindings files

Add a `doc` field to a binding. It's a string meant to contain
markdown.

Add subcommand `subplot libdocgen YAML -o MD` to read a bindings file
and output a markdown file documenting the steps in the bindings file,
and the type of captures, and the documentation for the step.

Signed-off-by: Lars Wirzenius <liw@liw.fi>
Sponsored-by: author

1 files changed, 87 insertions, 2 deletions

diff --git a/src/bin/subplot.rs b/src/bin/subplot.rs
index 6c118d4..40f0f55 100644
--- a/src/bin/subplot.rs
+++ b/src/bin/subplot.rs
@@ -6,8 +6,8 @@ use anyhow::Result;
 use env_logger::fmt::Color;
 use log::{debug, error, info, trace, warn};
 use subplot::{
-    codegen, load_document, resource, Document, EmbeddedFile, MarkupOpts, Style, SubplotError,
-    Warnings,
+    codegen, load_document, resource, Binding, Bindings, Document, EmbeddedFile, MarkupOpts, Style,
+    SubplotError, Warnings,
 };
 use time::{format_description::FormatItem, macros::format_description, OffsetDateTime};
 
@@ -58,6 +58,8 @@ enum Cmd {
     Codegen(Codegen),
     #[clap(hide = true)]
     Resources(Resources),
+    #[clap(hide = true)]
+    Libdocgen(Libdocgen),
 }
 
 impl Cmd {
@@ -68,6 +70,7 @@ impl Cmd {
             Cmd::Docgen(d) => d.run(),
             Cmd::Codegen(c) => c.run(),
             Cmd::Resources(r) => r.run(),
+            Cmd::Libdocgen(r) => r.run(),
         }
     }
 
@@ -78,6 +81,7 @@ impl Cmd {
             Cmd::Docgen(d) => d.doc_path(),
             Cmd::Codegen(c) => c.doc_path(),
             Cmd::Resources(r) => r.doc_path(),
+            Cmd::Libdocgen(r) => r.doc_path(),
         }
     }
 }
@@ -371,6 +375,87 @@ impl Codegen {
     }
 }
 
+#[derive(Debug, Parser)]
+/// Generate test suites from Subplot documents
+///
+/// This reads a subplot document, extracts the scenarios, and writes out a test
+/// program capable of running the scenarios in the subplot document.
+struct Libdocgen {
+    // Bindings file to read.
+    input: PathBuf,
+
+    // Output document filename
+    #[clap(name = "FILE", long = "output", short = 'o')]
+    output: PathBuf,
+
+    /// The template to use from the document.
+    ///
+    /// If not specified, subplot will try and find a unique template name from the document
+    #[clap(name = "TEMPLATE", long = "template", short = 't')]
+    template: Option<String>,
+}
+
+impl Libdocgen {
+    fn doc_path(&self) -> Option<&Path> {
+        None
+    }
+
+    fn run(&self) -> Result<()> {
+        debug!("libdocgen starts");
+
+        let mut bindings = Bindings::new();
+        bindings.add_from_file(&self.input, None)?;
+        // println!("{:#?}", bindings);
+
+        let mut doc = LibDoc::new(&self.input);
+        for b in bindings.bindings() {
+            // println!("{} {}", b.kind(), b.pattern());
+            doc.push_binding(b);
+        }
+
+        std::fs::write(&self.output, doc.to_markdown())?;
+
+        debug!("libdogen ends successfully");
+        Ok(())
+    }
+}
+
+struct LibDoc {
+    filename: PathBuf,
+    bindings: Vec<Binding>,
+}
+
+impl LibDoc {
+    fn new(filename: &Path) -> Self {
+        Self {
+            filename: filename.into(),
+            bindings: vec![],
+        }
+    }
+
+    fn push_binding(&mut self, binding: &Binding) {
+        self.bindings.push(binding.clone());
+    }
+
+    fn to_markdown(&self) -> String {
+        let mut md = String::new();
+        md.push_str(&format!("# Library `{}`\n\n", self.filename.display()));
+        for b in self.bindings.iter() {
+            md.push_str(&format!("\n## {} `{}`\n", b.kind(), b.pattern()));
+            if let Some(doc) = b.doc() {
+                md.push_str(&format!("\n{}\n", doc));
+            }
+            if b.types().count() > 0 {
+                md.push_str("\nCaptures:\n\n");
+                for (name, cap_type) in b.types() {
+                    md.push_str(&format!("- `{}`: {}\n", name, cap_type.as_str()));
+                }
+            }
+        }
+        md
+    }
+}
+
 fn load_linted_doc(
     filename: &Path,
     style: Style,