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, 65 insertions, 0 deletions

diff --git a/share/common/lib/runcmd.yaml b/share/common/lib/runcmd.yaml
index 7be2c05..0a387ed 100644
--- a/share/common/lib/runcmd.yaml
+++ b/share/common/lib/runcmd.yaml
@@ -8,6 +8,8 @@
       function: subplotlib::steplibrary::runcmd::helper_script
   types:
     script: file
+  doc: |
+    FIXME.
 
 - given: srcdir is in the PATH
   impl:
@@ -15,6 +17,10 @@
       function: runcmd_helper_srcdir_path
     rust:
       function: subplotlib::steplibrary::runcmd::helper_srcdir_path
+  doc: |
+    Make sure the source directory of the project being testes is on
+    the shell PATH. This makes it easy for tests to invoke programs
+    from the source tree.
 
 - when: I run {argv0}{args:text}
   impl:
@@ -22,6 +28,8 @@
       function: runcmd_step
     rust:
       function: subplotlib::steplibrary::runcmd::run
+  doc: |
+    Run a program, and make sure it succeeds.
 
 - when: I run, in {dirname}, {argv0}{args}
   impl:
@@ -33,6 +41,9 @@
     dirname: path
     argv0: word
     args: text
+  doc: |
+    Change to a different directory and run a program, and make sure
+    it succeeds;
 
 - when: I try to run {argv0}{args:text}
   impl:
@@ -40,6 +51,9 @@
       function: runcmd_try_to_run
     rust:
       function: subplotlib::steplibrary::runcmd::try_to_run
+  doc: |
+    Run a program, but allow it to fail. Other steps can check if it
+    succeeded.
 
 - when: I try to run, in {dirname}, {argv0}{args}
   impl:
@@ -51,6 +65,9 @@
     dirname: path
     argv0: word
     args: text
+  doc: |
+    Change to a different directory and run a program, but allow it to
+    fail. Other steps can check if it succeeded.
 
 # Steps to examine exit code of latest command.
 
@@ -62,6 +79,9 @@
       function: subplotlib::steplibrary::runcmd::exit_code_is
   types:
     exit: int
+  doc: |
+    Make sure the latest command run by `lib/runcmd` had a specific
+    exit code.
 
 - then: exit code is not {exit}
   impl:
@@ -71,6 +91,9 @@
       function: subplotlib::steplibrary::runcmd::exit_code_is_not
   types:
     exit: int
+  doc: |
+    Make sure the latest command run by `lib/runcmd` did not have a
+    specific exit code.
 
 - then: command is successful
   impl:
@@ -78,6 +101,9 @@
       function: runcmd_exit_code_is_zero
     rust:
       function: subplotlib::steplibrary::runcmd::exit_code_is_zero
+  doc: |
+    Make sure the latest command run by `lib/runcmd` indicated the
+    command succeeded.
 
 - then: command fails
   impl:
@@ -85,6 +111,9 @@
       function: runcmd_exit_code_is_nonzero
     rust:
       function: subplotlib::steplibrary::runcmd::exit_code_is_nonzero
+  doc: |
+    Make sure the latest command run by `lib/runcmd` indicated the
+    command failed.
 
 # Steps to examine stdout/stderr for exact content.
 
@@ -94,6 +123,9 @@
       function: runcmd_stdout_is
     rust:
       function: subplotlib::steplibrary::runcmd::stdout_is
+  doc: |
+    Make sure the standard output of the latest command run by
+    `lib/runcmd` is exactly as desired.
 
 - then: 'stdout isn''t exactly "{text:text}"'
   impl:
@@ -101,6 +133,9 @@
       function: runcmd_stdout_isnt
     rust:
       function: subplotlib::steplibrary::runcmd::stdout_isnt
+  doc: |
+    Make sure the standard output of the latest command run by
+    `lib/runcmd` is different from what is not wanted.
 
 - then: stderr is exactly "{text:text}"
   impl:
@@ -108,6 +143,9 @@
       function: runcmd_stderr_is
     rust:
       function: subplotlib::steplibrary::runcmd::stderr_is
+  doc: |
+    Make sure the standard error output of the latest command run by
+    `lib/runcmd` is exactly as desired.
 
 - then: 'stderr isn''t exactly "{text:text}"'
   impl:
@@ -115,6 +153,9 @@
       function: runcmd_stderr_isnt
     rust:
       function: subplotlib::steplibrary::runcmd::stderr_isnt
+  doc: |
+    Make sure the standard error output of the latest command run by
+    `lib/runcmd` is different from what is not wanted.
 
 # Steps to examine stdout/stderr for sub-strings.
 
@@ -124,6 +165,9 @@
       function: runcmd_stdout_contains
     rust:
       function: subplotlib::steplibrary::runcmd::stdout_contains
+  doc: |
+    Make sure the standard output of the latest command run by
+    `lib/runcmd` contains the desired sub-string.
 
 - then: 'stdout doesn''t contain "{text:text}"'
   impl:
@@ -131,6 +175,9 @@
       function: runcmd_stdout_doesnt_contain
     rust:
       function: subplotlib::steplibrary::runcmd::stdout_doesnt_contain
+  doc: |
+    Make sure the standard output of the latest command run by
+    `lib/runcmd` does not contain the sub-string.
 
 - then: stderr contains "{text:text}"
   impl:
@@ -138,6 +185,9 @@
       function: runcmd_stderr_contains
     rust:
       function: subplotlib::steplibrary::runcmd::stderr_contains
+  doc: |
+    Make sure the standard output of the latest command run by
+    `lib/runcmd` contains the desired sub-string.
 
 - then: 'stderr doesn''t contain "{text:text}"'
   impl:
@@ -145,6 +195,9 @@
       function: runcmd_stderr_doesnt_contain
     rust:
       function: subplotlib::steplibrary::runcmd::stderr_doesnt_contain
+  doc: |
+    Make sure the standard error output of the latest command run by
+    `lib/runcmd` does not contain the sub-string.
 
 # Steps to match stdout/stderr against regular expressions.
 
@@ -154,6 +207,9 @@
       function: runcmd_stdout_matches_regex
     rust:
       function: subplotlib::steplibrary::runcmd::stdout_matches_regex
+  doc: |
+    Make sure the standard output of the latest command run by
+    `lib/runcmd` matches the desired regular expression.
 
 - then: stdout doesn't match regex {regex:text}
   impl:
@@ -161,6 +217,9 @@
       function: runcmd_stdout_doesnt_match_regex
     rust:
       function: subplotlib::steplibrary::runcmd::stdout_doesnt_match_regex
+  doc: |
+    Make sure the standard output of the latest command run by
+    `lib/runcmd` does not match a regular expression.
 
 - then: stderr matches regex {regex:text}
   impl:
@@ -168,6 +227,9 @@
       function: runcmd_stderr_matches_regex
     rust:
       function: subplotlib::steplibrary::runcmd::stderr_matches_regex
+  doc: |
+    Make sure the standard error output of the latest command run by
+    `lib/runcmd` matches the desired regular expression.
 
 - then: stderr doesn't match regex {regex:text}
   impl:
@@ -175,3 +237,6 @@
       function: runcmd_stderr_doesnt_match_regex
     rust:
       function: subplotlib::steplibrary::runcmd::stderr_doesnt_match_regex
+  doc: |
+    Make sure the standard error output of the latest command run by
+    `lib/runcmd` does not match a regular expression.