From 89019d3e11ed3199a6bf631ea3cf9831fa0e17b8 Mon Sep 17 00:00:00 2001
From: Scott Rossillo <scott@rossillo.net>
Date: Tue, 27 Sep 2022 21:52:38 -0400
Subject: [PATCH 1/3] Provide better CLI help

---
 src/cli.rs  |  8 +++++++-
 src/main.rs | 15 ++++++++++-----
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/src/cli.rs b/src/cli.rs
index 4697a28..391cdcf 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -2,7 +2,7 @@ use clap::{Subcommand};
 use clap::Parser;
 
 #[derive(Debug, Parser)]
-#[clap(name = "github-action-doc")]
+#[clap(name = "github-action-doc", version)]
 #[clap(about = "A GitHub action & workflow readme writer", long_about = None)]
 pub struct Cli {
     #[clap(subcommand)]
@@ -14,12 +14,18 @@ pub enum Commands {
     #[clap(arg_required_else_help = true)]
     #[clap(about = "Generate documentation for a Github action", long_about = None)]
     Action {
+        /// Action YAML file
         #[clap(required = true, value_parser)]
         action_file: String
     },
     #[clap(arg_required_else_help = true)]
     #[clap(about = "Generate documentation for a Github workflow", long_about = None)]
     Workflow {
+        /// Full with to the output file to write workflow documentation to
+        #[clap(short = 'o', value_name = "OUTPUT_FILE", value_parser)]
+        output_file: Option<String>,
+
+        /// Workflow YAML file
         #[clap(required = true, value_parser)]
         workflow_file: String
     }
diff --git a/src/main.rs b/src/main.rs
index 6e653e4..dc80fe4 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -22,14 +22,19 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
             let readme_path = Path::new(&action_file).to_path_buf().parent().unwrap().join("README.md");
             fs::write(readme_path.to_str().unwrap(), gha.to_markdown().to_string()).expect("Unable to write readme");
         }
-        cli::Commands::Workflow { workflow_file} => {
+        cli::Commands::Workflow { workflow_file, output_file } => {
             let workflow = GitHubWorkflow::parse(&workflow_file)
                 .expect("Unable to parse workflow");
             let wf_path = Path::new(&workflow_file).to_path_buf();
-            let readme_path = wf_path
-                .parent()
-                .unwrap()
-                .join(&format!("{}.md", wf_path.file_stem().unwrap().to_str().unwrap()));
+            let readme_path = match output_file {
+                Some(out) => { Path::new(&out).to_path_buf() },
+                None => {
+                    wf_path
+                        .parent()
+                        .unwrap()
+                        .join(&format!("{}.md", wf_path.file_stem().unwrap().to_str().unwrap()))
+                }
+            };
 
             println!("Writing workflow readme {:?}", &readme_path);
             fs::write(readme_path.to_str().unwrap(), workflow.to_markdown().to_string()).expect("Unable to write readme");

From 0bf9ddf4644c20dd41afdb533de7d8e4f96bfa31 Mon Sep 17 00:00:00 2001
From: Scott Rossillo <scott@rossillo.net>
Date: Tue, 27 Sep 2022 21:57:29 -0400
Subject: [PATCH 2/3] update readme

---
 README.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index a71650d..4349f60 100644
--- a/README.md
+++ b/README.md
@@ -15,11 +15,10 @@ USAGE:
     github-action-doc action <ACTION_FILE>
 
 ARGS:
-    <ACTION_FILE>
+    <ACTION_FILE>    Action YAML file
 
 OPTIONS:
     -h, --help    Print help information
-
 ```
 
 ### Documenting GitHub Workflows
@@ -29,13 +28,14 @@ $ github-action-doc workflow -h
 Generate documentation for a Github workflow
 
 USAGE:
-    github-action-doc workflow <WORKFLOW_FILE>
+    github-action-doc workflow [OPTIONS] <WORKFLOW_FILE>
 
 ARGS:
-    <WORKFLOW_FILE>
+    <WORKFLOW_FILE>    Workflow YAML file
 
 OPTIONS:
-    -h, --help    Print help information
+    -h, --help              Print help information
+    -o <OUTPUT_FILE>        Full with to the output file to write workflow documentation to
 ```
 
 ## Examples

From ea02441d2db3ab6e94f093a4031087830ab06e18 Mon Sep 17 00:00:00 2001
From: Scott Rossillo <scott@rossillo.net>
Date: Tue, 27 Sep 2022 22:03:18 -0400
Subject: [PATCH 3/3] update docs on workflow output file

---
 README.md  | 3 ++-
 src/cli.rs | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 4349f60..c8122ab 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,8 @@ ARGS:
 
 OPTIONS:
     -h, --help              Print help information
-    -o <OUTPUT_FILE>        Full with to the output file to write workflow documentation to
+    -o <OUTPUT_FILE>        Optional path to the output file to write workflow documentation to;
+                            defaults to `<WORKFLOW_FILE>.md`, replacing the YAML file extension
 ```
 
 ## Examples
diff --git a/src/cli.rs b/src/cli.rs
index 391cdcf..476f958 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -21,7 +21,8 @@ pub enum Commands {
     #[clap(arg_required_else_help = true)]
     #[clap(about = "Generate documentation for a Github workflow", long_about = None)]
     Workflow {
-        /// Full with to the output file to write workflow documentation to
+        /// Optional path to the output file to write workflow documentation to;
+        /// defaults to `<WORKFLOW_FILE>.md`, replacing the YAML file extension.
         #[clap(short = 'o', value_name = "OUTPUT_FILE", value_parser)]
         output_file: Option<String>,