feat: add --open flag to wdl doc dev tool

Cargo.toml

@@ -66,6 +66,7 @@ url = "2.5.2"
 urlencoding = "2.1.3"
 uuid = "1.10.0"
 walkdir = "2.5.0"
+webbrowser = "1.0.3"
 
 [workspace.lints.rust]
 missing_docs = "warn"

wdl/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+* Implemented the `wdl doc` subcommand for generating documentation (**currently in ALPHA testing**) ([#248](https://github.com/stjude-rust-labs/wdl/pull/248)).
+* Added an `--open` flag to `wdl doc` subcommand ([#269](https://github.com/stjude-rust-labs/wdl/pull/269)).
 * Added the `engine` module containing the implementation of `wdl-engine` ([#265](https://github.com/stjude-rust-labs/wdl/pull/265)).
 * Implemented the `wdl run` subcommand for running tasks ([#265](https://github.com/stjude-rust-labs/wdl/pull/265)).
 

wdl/Cargo.toml

@@ -32,6 +32,7 @@ clap-verbosity-flag =  { workspace = true, optional = true }
 tracing-log = { workspace = true, optional = true }
 tracing = { workspace = true, optional = true }
 url = { workspace = true, optional = true }
+webbrowser = { workspace = true, optional = true }
 
 [dev-dependencies]
 clap = { workspace = true }
@@ -67,6 +68,7 @@ cli = [
     "dep:tracing",
     "dep:url",
     "dep:serde_json",
+    "dep:webbrowser",
 ]
 
 [lints]

wdl/src/bin/wdl.rs

@@ -394,19 +394,56 @@ impl FormatCommand {
     }
 }
 
+/// Finds a file matching the given name in the given directory.
+///
+/// This function will return the first match it finds, at any depth.
+fn find_file_in_directory(name: &str, dir: &Path) -> Option<PathBuf> {
+    fs::read_dir(dir)
+        .ok()?
+        .filter_map(|entry| entry.ok())
+        .find_map(|entry| {
+            let path = entry.path();
+            if path.is_dir() {
+                find_file_in_directory(name, &path)
+            } else if path.file_name().map(|f| f == name).unwrap_or(false) {
+                Some(path)
+            } else {
+                None
+            }
+        })
+}
+
 /// Document a workspace.
 #[derive(Args)]
 #[clap(disable_version_flag = true)]
 pub struct DocCommand {
     /// The path to the workspace.
     #[clap(value_name = "PATH")]
     pub path: PathBuf,
+
+    /// Whether or not to open the generated documentation in the default
+    /// browser.
+    #[clap(long)]
+    pub open: bool,
 }
 
 impl DocCommand {
     /// Executes the `document` subcommand.
     async fn exec(self) -> Result<()> {
-        document_workspace(self.path).await
+        document_workspace(self.path.clone()).await?;
+
+        if self.open {
+            // find the first `$path/docs/**/index.html` file in the workspace
+            // TODO: once we have a homepage, open that instead.
+            if let Some(index) = find_file_in_directory("index.html", &self.path.join("docs")) {
+                webbrowser::open(&index.as_path().to_string_lossy())
+                    .context("failed to open browser")?;
+            } else {
+                eprintln!("failed to find `index.html` in workspace");
+            }
+        }
+
+        Ok(())
     }
 }