Add exit codes to man page

Author: thomas-zahner

README.md

@@ -672,10 +672,13 @@ Options:
 
 ### Exit codes
 
-- `0` for success (all links checked successfully or excluded/skipped as configured)
-- `1` for missing inputs and any unexpected runtime failures or config errors
-- `2` for link check failures (if any non-excluded link failed the check)
-- `3` for errors in the config file
+0   Success. The operation was completed successfully as instructed.
+
+1   Missing inputs or any unexpected runtime failures or configuration errors
+
+2   Link check failures. At least one non-excluded link failed the check.
+
+3   Encountered errors in the config file.
 
 ### Ignoring links
 

lychee-bin/src/commands/generate.rs

@@ -5,12 +5,25 @@
 
 use anyhow::Result;
 use clap::{CommandFactory, crate_authors};
+use clap_mangen::{
+    Man,
+    roff::{Roff, roman},
+};
 use serde::Deserialize;
 use strum::{Display, EnumIter, EnumString, VariantNames};
 
 use crate::LycheeOptions;
 
 const CONTRIBUTOR_THANK_NOTE: &str = "\n\nA huge thank you to all the wonderful contributors who helped make this project a success.";
+const EXIT_CODE_DESCRIPTION: &'static str = "
+0   Success. The operation was completed successfully as instructed.
+
+1   Missing inputs or any unexpected runtime failures or configuration errors
+
+2   Link check failures. At least one non-excluded link failed the check.
+
+3   Encountered errors in the config file.
+";
 
 /// What to generate when provided the --generate flag
 #[derive(Debug, Deserialize, Clone, Display, EnumIter, EnumString, VariantNames, PartialEq)]
@@ -33,22 +46,38 @@ fn man_page() -> Result<String> {
     let date = chrono::offset::Local::now().format("%Y-%m-%d");
     let authors = crate_authors!("\n\n").to_owned() + CONTRIBUTOR_THANK_NOTE;
 
-    let man =
-        clap_mangen::Man::new(LycheeOptions::command().author(authors)).date(format!("{date}"));
-
+    let man = Man::new(LycheeOptions::command().author(authors)).date(format!("{date}"));
     let mut buffer: Vec<u8> = Vec::default();
-    man.render(&mut buffer)?;
+
+    // Manually customise `Man::render` (see https://github.com/clap-rs/clap/issues/3354)
+    man.render_title(&mut buffer)?;
+    man.render_name_section(&mut buffer)?;
+    man.render_synopsis_section(&mut buffer)?;
+    man.render_description_section(&mut buffer)?;
+    man.render_options_section(&mut buffer)?;
+    render_exit_codes(&mut buffer)?;
+    man.render_version_section(&mut buffer)?;
+    man.render_authors_section(&mut buffer)?;
 
     Ok(std::str::from_utf8(&buffer)?.to_owned())
 }
 
+fn render_exit_codes(buffer: &mut Vec<u8>) -> Result<(), anyhow::Error> {
+    let mut roff = Roff::default();
+    roff.control("SH", ["EXIT CODES"]);
+    roff.text([roman(EXIT_CODE_DESCRIPTION)]);
+    roff.to_writer(buffer)?;
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::man_page;
+    use crate::generate::EXIT_CODE_DESCRIPTION;
     use anyhow::Result;
 
     #[test]
-    fn test_man_pages() -> Result<()> {
+    fn test_man_page() -> Result<()> {
         let roff = man_page()?;
 
         // Must contain description
@@ -67,4 +96,34 @@ mod tests {
         assert_eq!(roff.matches("\\-\\-version").count(), 2);
         Ok(())
     }
+
+    /// Test that the Exit Codes section in `README.md` is up to date with
+    /// lychee's manual page.
+    #[test]
+    #[cfg(unix)]
+    fn test_readme_exit_codes_up_to_date() -> Result<(), Box<dyn std::error::Error>> {
+        use test_utils::load_readme_text;
+
+        const BEGIN: &str = "### Exit codes";
+        const END: &str = "# ";
+
+        let readme = load_readme_text!();
+        let start = readme.find(BEGIN).ok_or("Beginning not found in README")? + BEGIN.len();
+        let end = readme[start..].find(END).ok_or("End not found in README")? - END.len();
+
+        let section = &readme[start..start + end];
+        assert_eq!(
+            filter_empty_lines(section),
+            filter_empty_lines(EXIT_CODE_DESCRIPTION)
+        );
+
+        Ok(())
+    }
+
+    fn filter_empty_lines(s: &str) -> String {
+        s.lines()
+            .filter(|line| !line.trim().is_empty())
+            .collect::<Vec<_>>()
+            .join("\n")
+    }
 }

lychee-bin/tests/usage.rs

@@ -1,7 +1,5 @@
 #[cfg(test)]
 mod readme {
-    use std::{fs, path::Path};
-
     use assert_cmd::Command;
     use pretty_assertions::assert_eq;
 
@@ -12,14 +10,6 @@ mod readme {
         Command::cargo_bin(env!("CARGO_PKG_NAME")).expect("Couldn't get cargo package name")
     }
 
-    fn load_readme_text() -> String {
-        let readme_path = Path::new(env!("CARGO_MANIFEST_DIR"))
-            .parent()
-            .unwrap()
-            .join("README.md");
-        fs::read_to_string(readme_path).unwrap()
-    }
-
     /// Remove line `[default: lychee/x.y.z]` from the string
     fn remove_lychee_version_line(string: &str) -> String {
         string
@@ -44,6 +34,8 @@ mod readme {
     #[test]
     #[cfg(unix)]
     fn test_readme_usage_up_to_date() -> Result<(), Box<dyn std::error::Error>> {
+        use test_utils::load_readme_text;
+
         let mut cmd = main_command();
 
         let help_cmd = cmd.env_clear().arg("--help").assert().success();
@@ -54,7 +46,7 @@ mod readme {
         let usage_in_help = &help_output[usage_in_help_start..];
 
         let usage_in_help = trim_empty_lines(&remove_lychee_version_line(usage_in_help));
-        let readme = load_readme_text();
+        let readme = load_readme_text!();
         let usage_start = readme
             .find(USAGE_STRING)
             .ok_or("Usage not found in README")?;

test-utils/src/lib.rs

@@ -149,3 +149,14 @@ macro_rules! fixture_uri {
             .expect("expected subpath to form a valid URL")
     }};
 }
+
+#[macro_export]
+macro_rules! load_readme_text {
+    () => {{
+        let readme_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+            .parent()
+            .unwrap()
+            .join("README.md");
+        std::fs::read_to_string(readme_path).unwrap()
+    }};
+}