Generate man pages for Volta

Cargo.toml

@@ -1,7 +1,10 @@
 [package]
 name = "volta"
 version = "2.0.1"
-authors = ["David Herman <david.herman@gmail.com>", "Charles Pierce <cpierce.grad@gmail.com>"]
+authors = [
+    "David Herman <david.herman@gmail.com>",
+    "Charles Pierce <cpierce.grad@gmail.com>",
+]
 license = "BSD-2-Clause"
 repository = "https://github.com/volta-cli/volta"
 edition = "2021"
@@ -38,6 +41,7 @@ textwrap = "0.16.1"
 which = "6.0.3"
 dirs = "5.0.1"
 volta-migrate = { path = "crates/volta-migrate" }
+clap_mangen = "0.2.23"
 
 [target.'cfg(windows)'.dependencies]
 winreg = "0.52.0"

crates/volta-core/src/error/kind.rs

@@ -530,6 +530,11 @@ pub enum ErrorKind {
     YarnVersionNotFound {
         matching: String,
     },
+
+    /// Thrown when there is an error writing the man pages to a file
+    ManPagesOutFileError {
+        path: PathBuf,
+    },
 }
 
 impl fmt::Display for ErrorKind {
@@ -1452,6 +1457,14 @@ Please verify your internet connection.",
 Please verify that the version is correct."#,
                 matching
             ),
+            ErrorKind::ManPagesOutFileError { path } => write!(
+                f,
+                "Could not write man pages to {}
+
+{}",
+                path.display(),
+                PERMISSIONS_CTA
+            ),
         }
     }
 }
@@ -1577,6 +1590,7 @@ impl ErrorKind {
             ErrorKind::Yarn2NotSupported => ExitCode::NoVersionMatch,
             ErrorKind::YarnLatestFetchError { .. } => ExitCode::NetworkError,
             ErrorKind::YarnVersionNotFound { .. } => ExitCode::NoVersionMatch,
+            ErrorKind::ManPagesOutFileError { .. } => ExitCode::FileSystemError,
         }
     }
 }

crates/volta-core/src/session.rs

@@ -38,6 +38,7 @@ pub enum ActivityKind {
     Setup,
     Run,
     Args,
+    ManPages,
 }
 
 impl Display for ActivityKind {
@@ -66,6 +67,7 @@ impl Display for ActivityKind {
             ActivityKind::Which => "which",
             ActivityKind::Run => "run",
             ActivityKind::Args => "args",
+            ActivityKind::ManPages => "man-pages",
         };
         f.write_str(s)
     }

dev/unix/volta-install.sh

@@ -191,6 +191,22 @@ create_tree() {
   fi
 }
 
+generate_man_page() {
+  local install_dir="$1"
+  local man_dir="$install_dir/share/man/man1"
+
+  info 'Generating' "man page"
+
+  mkdir -p "$man_dir"
+
+  if ! "$install_dir/bin/volta" man > "$man_dir/volta.1" 2>/dev/null; then
+    warning "Failed to generate man page. Man pages may not be available."
+    return 1
+  fi
+
+  info 'Generated' "man page at $man_dir/volta.1"
+}
+
 install_version() {
   local version_to_install="$1"
   local install_dir="$2"
@@ -223,6 +239,7 @@ install_version() {
 
   if [ "$?" == 0 ]
   then
+      generate_man_page "$install_dir"
       if [ "$should_run_setup" == "true" ]; then
         info 'Finished' "installation. Updating user profile settings."
         "$install_dir"/bin/volta setup

src/cli.rs

@@ -101,6 +101,9 @@ pub(crate) enum Subcommand {
 
     /// Run a command with custom Node, npm, pnpm, and/or Yarn versions
     Run(command::Run),
+
+    /// Man pages
+    Man(command::ManPages),
 }
 
 impl Subcommand {
@@ -116,6 +119,7 @@ impl Subcommand {
             Subcommand::Use(r#use) => r#use.run(session),
             Subcommand::Setup(setup) => setup.run(session),
             Subcommand::Run(run) => run.run(session),
+            Subcommand::Man(man) => man.run(session),
         }
     }
 }

src/command/man_pages.rs

@@ -0,0 +1,84 @@
+use std::path::PathBuf;
+
+use clap::CommandFactory;
+use clap_mangen::Man;
+use log::info;
+
+use volta_core::{
+    error::{Context, ErrorKind, ExitCode, Fallible},
+    session::{ActivityKind, Session},
+    style::{note_prefix, success_prefix},
+};
+
+use crate::command::Command;
+
+#[derive(Debug, clap::Args)]
+pub(crate) struct ManPages {
+    /// File to write generated man pages to
+    #[arg(short, long = "output")]
+    out_file: Option<PathBuf>,
+
+    /// Write over an existing file, if any.
+    #[arg(short, long)]
+    force: bool,
+}
+
+impl Command for ManPages {
+    fn run(self, session: &mut Session) -> Fallible<ExitCode> {
+        session.add_event_start(ActivityKind::ManPages);
+
+        let app = crate::cli::Volta::command();
+        let man = Man::new(app);
+
+        match self.out_file {
+            Some(path) => {
+                if path.is_file() && !self.force {
+                    return Err(ErrorKind::ManPagesOutFileError { path }.into());
+                }
+
+                // Create parent directory if it doesn't exist
+                if let Some(parent) = path.parent() {
+                    if !parent.is_dir() {
+                        info!(
+                            "{} {} does not exist, creating it",
+                            note_prefix(),
+                            parent.display()
+                        );
+                        std::fs::create_dir_all(parent).with_context(|| {
+                            ErrorKind::CreateDirError {
+                                dir: parent.to_path_buf(),
+                            }
+                        })?;
+                    }
+                }
+
+                let mut file = std::fs::File::create(&path).with_context(|| {
+                    ErrorKind::ManPagesOutFileError {
+                        path: path.to_path_buf(),
+                    }
+                })?;
+
+                man.render(&mut file)
+                    .map_err(|_e| ErrorKind::ManPagesOutFileError {
+                        path: path.to_path_buf(),
+                    })?;
+
+                info!(
+                    "{} generated man pages to {}",
+                    success_prefix(),
+                    path.display()
+                );
+            }
+            None => {
+                man.render(&mut std::io::stdout()).map_err(|_e| {
+                    ErrorKind::ManPagesOutFileError {
+                        path: PathBuf::from("stdout"),
+                    }
+                })?;
+            }
+        };
+
+        session.add_event_end(ActivityKind::ManPages, ExitCode::Success);
+        Ok(ExitCode::Success)
+    }
+}

src/command/mod.rs

@@ -2,6 +2,7 @@ pub(crate) mod completions;
 pub(crate) mod fetch;
 pub(crate) mod install;
 pub(crate) mod list;
+pub(crate) mod man_pages;
 pub(crate) mod pin;
 pub(crate) mod run;
 pub(crate) mod setup;
@@ -14,6 +15,7 @@ pub(crate) use completions::Completions;
 pub(crate) use fetch::Fetch;
 pub(crate) use install::Install;
 pub(crate) use list::List;
+pub(crate) use man_pages::ManPages;
 pub(crate) use pin::Pin;
 pub(crate) use r#use::Use;
 pub(crate) use run::Run;