[WIP] add a command to install man pages

cargo-nextest/Cargo.toml

@@ -15,6 +15,7 @@ rust-version = "1.59"
 camino = "1.0.9"
 cfg-if = "1.0.0"
 clap = { version = "3.2.6", features = ["derive", "env"] }
+clap_mangen = "0.1.9"
 # we don't use the tracing support
 color-eyre = { version = "0.6.1", default-features = false }
 dialoguer = "0.10.1"
@@ -23,6 +24,7 @@ enable-ansi-support = "0.1.2"
 # we don't use the default formatter so we don't need default features
 env_logger = { version = "0.9.0", default-features = false }
 guppy = "0.14.2"
+home = "0.5.3"
 log = "0.4.17"
 itertools = "0.10.3"
 miette = { version = "4.7.1", features = ["fancy"] }

cargo-nextest/src/dispatch.rs

@@ -3,6 +3,7 @@
 
 use crate::{
     cargo_cli::{CargoCli, CargoOptions},
+    mangen::install_man,
     output::{OutputContext, OutputOpts, OutputWriter},
     reuse_build::{make_path_mapper, ArchiveFormatOpt, ReuseBuildOpts},
     ExpectedError, Result, ReuseBuildKind,
@@ -55,14 +56,20 @@ impl CargoNextestApp {
 }
 
 #[derive(Debug, Subcommand)]
-enum NextestSubcommand {
+pub(crate) enum NextestSubcommand {
     /// A next-generation test runner for Rust. <https://nexte.st>
     Nextest(AppOpts),
 }
 
-#[derive(Debug, Args)]
+/// cargo-nextest is a next-generation test runner for Rust projects.
+///
+/// Nextest runs tests in parallel and provides a rich set of features, such as partitioning test
+/// runs, JUnit output, and archiving and reusing builds.
+///
+/// For the full documentation, see the nextest site at <https://nexte.st>.
+#[derive(Debug, Parser)]
 #[clap(version)]
-struct AppOpts {
+pub(crate) struct AppOpts {
     /// Path to Cargo.toml
     #[clap(long, global = true, value_name = "PATH")]
     manifest_path: Option<Utf8PathBuf>,
@@ -1018,6 +1025,12 @@ impl App {
 
 #[derive(Debug, Subcommand)]
 enum SelfCommand {
+    /// Install man pages for nextest.
+    InstallMan {
+        /// The output directory [default: <current-exe-path>/../man]
+        output_dir: Option<Utf8PathBuf>,
+    },
+
     #[cfg_attr(
         not(feature = "self-update"),
         doc = "This version of nextest does not have self-update enabled\n\
@@ -1064,6 +1077,10 @@ impl SelfCommand {
         let output = output.init();
 
         match self {
+            Self::InstallMan { output_dir } => {
+                install_man(output_dir)?;
+                Ok(0)
+            }
             Self::Update {
                 version,
                 check,

cargo-nextest/src/errors.rs

@@ -172,6 +172,11 @@ pub enum ExpectedError {
         reason: &'static str,
         args: Vec<String>,
     },
+    #[error(transparent)]
+    InstallManError {
+        #[from]
+        error: InstallManError,
+    },
 }
 
 impl ExpectedError {
@@ -311,6 +316,7 @@ impl ExpectedError {
                 NextestExitCode::EXPERIMENTAL_FEATURE_NOT_ENABLED
             }
             Self::FilterExpressionParseError { .. } => NextestExitCode::INVALID_FILTER_EXPRESSION,
+            Self::InstallManError { .. } => NextestExitCode::INSTALL_MAN_ERROR,
         }
     }
 
@@ -529,6 +535,11 @@ impl ExpectedError {
                 );
                 None
             }
+            Self::InstallManError { error } => {
+                // This is a transparent error.
+                log::error!("{}", error);
+                error.source()
+            }
         };
 
         while let Some(err) = next_error {
@@ -537,3 +548,25 @@ impl ExpectedError {
         }
     }
 }
+
+#[derive(Debug, Error)]
+#[doc(hidden)]
+pub enum InstallManError {
+    #[error("could not determine current executable path")]
+    CurrentExe {
+        #[source]
+        error: std::io::Error,
+    },
+    #[error("error creating output directory `{path}`")]
+    CreateOutputDir {
+        path: Utf8PathBuf,
+        #[source]
+        error: std::io::Error,
+    },
+    #[error("error writing to `{path}`")]
+    WriteToFile {
+        path: Utf8PathBuf,
+        #[source]
+        error: std::io::Error,
+    },
+}

cargo-nextest/src/lib.rs

@@ -16,6 +16,7 @@
 mod cargo_cli;
 mod dispatch;
 mod errors;
+mod mangen;
 mod output;
 mod reuse_build;
 #[cfg(feature = "self-update")]

nextest-metadata/src/exit_codes.rs

@@ -28,6 +28,9 @@ impl NextestExitCode {
     /// Writing data to stdout or stderr produced an error.
     pub const WRITE_OUTPUT_ERROR: i32 = 110;
 
+    /// Installing man pages produced an error.
+    pub const INSTALL_MAN_ERROR: i32 = 120;
+
     /// Downloading an update resulted in an error.
     pub const UPDATE_ERROR: i32 = 90;