tidy HTML for docs

automation-tasks-rs · Feb 9, 2024 · da4cf12 · da4cf12
1 parent fdce1db
commit da4cf12
Show file tree

Hide file tree

Showing 13 changed files with 247 additions and 221 deletions.
diff --git a/-e b/-e
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "cargo-auto"
-version = "2024.209.128"
+version = "2024.209.135"
 authors = ["bestia.dev"]
 homepage = "https://bestia.dev"
 edition = "2021"

diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 [//]: # (auto_cargo_toml_to_md start)
 
 **cargo-auto - automation tasks written in Rust language for the build process of Rust projects**  
-***version: 2024.209.128 date: 2024-02-09 author: [bestia.dev](https://bestia.dev) repository: [GitHub](https://github.com/bestia-dev/cargo-auto)***  
+***version: 2024.209.135 date: 2024-02-09 author: [bestia.dev](https://bestia.dev) repository: [GitHub](https://github.com/bestia-dev/cargo-auto)***  
 
 [//]: # (auto_cargo_toml_to_md end)
 
@@ -21,11 +21,11 @@
  ![Hits](https://bestia.dev/webpage_hit_counter/get_svg_image/959103982.svg)
 
 [//]: # (auto_lines_of_code start)
-[![Lines in Rust code](https://img.shields.io/badge/Lines_in_Rust-9181-green.svg)](https://github.com/bestia-dev/cargo-auto/)
-[![Lines in Doc comments](https://img.shields.io/badge/Lines_in_Doc_comments-471-blue.svg)](https://github.com/bestia-dev/cargo-auto/)
+[![Lines in Rust code](https://img.shields.io/badge/Lines_in_Rust-9179-green.svg)](https://github.com/bestia-dev/cargo-auto/)
+[![Lines in Doc comments](https://img.shields.io/badge/Lines_in_Doc_comments-1227-blue.svg)](https://github.com/bestia-dev/cargo-auto/)
 [![Lines in Comments](https://img.shields.io/badge/Lines_in_comments-349-purple.svg)](https://github.com/bestia-dev/cargo-auto/)
 [![Lines in examples](https://img.shields.io/badge/Lines_in_examples-0-yellow.svg)](https://github.com/bestia-dev/cargo-auto/)
-[![Lines in tests](https://img.shields.io/badge/Lines_in_tests-1526-orange.svg)](https://github.com/bestia-dev/cargo-auto/)
+[![Lines in tests](https://img.shields.io/badge/Lines_in_tests-1524-orange.svg)](https://github.com/bestia-dev/cargo-auto/)
 
 [//]: # (auto_lines_of_code end)
 

diff --git a/automation_tasks_rs/src/copy_files_to_strings_mod.rs b/automation_tasks_rs/src/copy_files_to_strings_mod.rs
@@ -7,7 +7,11 @@ use base64ct::Encoding;
 /// the string will be in a vector with the file name
 /// first we create the complete text, then we check if the old text needs to be replaced
 pub fn copy_folder_files_into_module(folder_path: &std::path::Path, module_path: &std::path::Path) {
-    println!("copy_folder_files_into_module {}, {}", folder_path.to_string_lossy(), module_path.to_string_lossy() );
+    println!(
+        "copy_folder_files_into_module {}, {}",
+        folder_path.to_string_lossy(),
+        module_path.to_string_lossy()
+    );
     // traverse and get all file_names
     let files = cargo_auto_lib::traverse_dir_with_exclude_dir(
         &folder_path,
@@ -18,55 +22,62 @@ pub fn copy_folder_files_into_module(folder_path: &std::path::Path, module_path:
     .unwrap();
     let mut new_code = String::new();
     for file_name in files.iter() {
-        let file_name_short = file_name.trim_start_matches(&format!("{}/",folder_path.to_string_lossy()));
+        let file_name_short = file_name.trim_start_matches(&format!("{}/", folder_path.to_string_lossy()));
         // avoid Cargo.lock file
-        if file_name_short=="Cargo.lock"{
+        if file_name_short == "Cargo.lock" {
             continue;
         }
-        let file_content = if 
-            file_name_short.ends_with(".ico") 
+        let file_content = if file_name_short.ends_with(".ico")
             || file_name_short.ends_with(".png")
             || file_name_short.ends_with(".woff2")
         {
             // convert binary file to base64
             let b = std::fs::read(&file_name).unwrap();
             base64ct::Base64::encode_string(&b)
-        }
-        else{
+        } else {
             // all others are text files
             // dbg!(&file_name_short);
             std::fs::read_to_string(&file_name).unwrap()
         };
 
-        new_code.push_str(&format!(r####"vec_file.push(crate::FileItem{{
+        new_code.push_str(&format!(
+            r####"vec_file.push(crate::FileItem{{
             file_name :"{}",
             file_content : r###"{}"###,
 }});    
-"####, &file_name_short, &file_content));
+"####,
+            &file_name_short, &file_content
+        ));
     }
 
     // read the content of the module, delimited by markers
-    let module_content =  std::fs::read_to_string(module_path).unwrap();
-    let start_pos = find_pos_start_data_after_delimiter(&module_content, 0, "// region: files copied into strings by automation tasks\n").expect("didn't find // region: files copied..");
-    let end_pos = find_pos_end_data_before_delimiter(&module_content, 0, "// endregion: files copied into strings by automation tasks").expect("didn't find // endregion: files copied..");
+    let module_content = std::fs::read_to_string(module_path).unwrap();
+    let start_pos = find_pos_start_data_after_delimiter(
+        &module_content,
+        0,
+        "// region: files copied into strings by automation tasks\n",
+    )
+    .expect("didn't find // region: files copied..");
+    let end_pos = find_pos_end_data_before_delimiter(
+        &module_content,
+        0,
+        "// endregion: files copied into strings by automation tasks",
+    )
+    .expect("didn't find // endregion: files copied..");
     let old_code = &module_content[start_pos..end_pos];
 
     // compare the text, if different replace
-    if old_code != new_code{       
+    if old_code != new_code {
         let mut new_module_content = String::new();
         new_module_content.push_str(&module_content[..start_pos]);
         new_module_content.push_str(&new_code);
         new_module_content.push_str(&module_content[end_pos..]);
-        std::fs::write(module_path, &new_module_content).unwrap();  
+        std::fs::write(module_path, &new_module_content).unwrap();
     }
 }
 
 /// return the position of start of the delimited data after the delimiter
-pub fn find_pos_start_data_after_delimiter(
-    md_text_content: &str,
-    pos: usize,
-    delimiter: &str,
-) -> Option<usize> {
+pub fn find_pos_start_data_after_delimiter(md_text_content: &str, pos: usize, delimiter: &str) -> Option<usize> {
     if let Some(pos_start_data) = find_from(md_text_content, pos, delimiter) {
         let pos_start_data = pos_start_data + delimiter.len();
         return Some(pos_start_data);
@@ -76,11 +87,7 @@ pub fn find_pos_start_data_after_delimiter(
 }
 
 /// return the position of end of the delimited data before the delimiter
-pub fn find_pos_end_data_before_delimiter(
-    md_text_content: &str,
-    pos: usize,
-    delimiter: &str,
-) -> Option<usize> {
+pub fn find_pos_end_data_before_delimiter(md_text_content: &str, pos: usize, delimiter: &str) -> Option<usize> {
     if let Some(pos_end_data) = find_from(md_text_content, pos, delimiter) {
         return Some(pos_end_data);
     }
@@ -100,4 +107,3 @@ pub fn find_from(text: &str, from_pos: usize, find: &str) -> Option<usize> {
         option_location
     }
 }
-
diff --git a/automation_tasks_rs/src/main.rs b/automation_tasks_rs/src/main.rs
@@ -7,10 +7,10 @@ use cargo_auto_lib as cl;
 // traits must be in scope (Rust strangeness)
 use cl::CargoTomlPublicApiMethods;
 
-use cargo_auto_lib::RED as RED;
-use cargo_auto_lib::YELLOW as YELLOW;
-use cargo_auto_lib::GREEN as GREEN;
-use cargo_auto_lib::RESET as RESET;
+use cargo_auto_lib::GREEN;
+use cargo_auto_lib::RED;
+use cargo_auto_lib::RESET;
+use cargo_auto_lib::YELLOW;
 // region: library with basic automation tasks
 
 use cargo_auto_github_lib::*;
@@ -90,12 +90,12 @@ fn print_help() {
 }
 
 /// all example commands in one place
-fn print_examples_cmd(){
-/*
-    println!(r#"{YELLOW}run examples:{RESET}
-{GREEN}cargo run --example example1{RESET}
-"#);
-*/
+fn print_examples_cmd() {
+    /*
+        println!(r#"{YELLOW}run examples:{RESET}
+    {GREEN}cargo run --example example1{RESET}
+    "#);
+    */
 }
 
 /// sub-command for bash auto-completion of `cargo auto` using the crate `dev_bestia_cargo_completion`
@@ -105,7 +105,15 @@ fn completion() {
     let last_word = args[3].as_str();
 
     if last_word == "cargo-auto" || last_word == "auto" {
-        let sub_commands = vec!["build", "release", "doc", "test", "commit_and_push", "publish_to_crates_io", "github_new_release"];
+        let sub_commands = vec![
+            "build",
+            "release",
+            "doc",
+            "test",
+            "commit_and_push",
+            "publish_to_crates_io",
+            "github_new_release",
+        ];
         cl::completion_return_one_or_more_sub_commands(sub_commands, word_being_completed);
     }
     /*
@@ -126,20 +134,24 @@ fn task_build() {
     let cargo_toml = cl::CargoToml::read();
 
     copy_files_to_strings_mod::copy_folder_files_into_module(
-        std::path::Path::new("template_new_auto"), 
-        std::path::Path::new("src/template_new_auto_mod.rs"));
-
+        std::path::Path::new("template_new_auto"),
+        std::path::Path::new("src/template_new_auto_mod.rs"),
+    );
+
     copy_files_to_strings_mod::copy_folder_files_into_module(
-        std::path::Path::new("template_new_cli"), 
-        std::path::Path::new("src/template_new_cli_mod.rs"));
+        std::path::Path::new("template_new_cli"),
+        std::path::Path::new("src/template_new_cli_mod.rs"),
+    );
 
     copy_files_to_strings_mod::copy_folder_files_into_module(
-        std::path::Path::new("template_new_wasm"), 
-        std::path::Path::new("src/template_new_wasm_mod.rs"));        
-
-        copy_files_to_strings_mod::copy_folder_files_into_module(
-    std::path::Path::new("template_new_pwa_wasm"), 
-    std::path::Path::new("src/template_new_pwa_wasm_mod.rs"));   
+        std::path::Path::new("template_new_wasm"),
+        std::path::Path::new("src/template_new_wasm_mod.rs"),
+    );
+
+    copy_files_to_strings_mod::copy_folder_files_into_module(
+        std::path::Path::new("template_new_pwa_wasm"),
+        std::path::Path::new("src/template_new_pwa_wasm_mod.rs"),
+    );
 
     cl::auto_version_increment_semver_or_date();
     cl::run_shell_command("cargo fmt");
@@ -151,29 +163,32 @@ fn task_build() {
     {YELLOW}if ok, then,{RESET}
 {GREEN}cargo auto release{RESET}
 "#,
-package_name = cargo_toml.package_name(),
+        package_name = cargo_toml.package_name(),
     );
     print_examples_cmd();
 }
 
 /// cargo build --release
 fn task_release() {
-
     copy_files_to_strings_mod::copy_folder_files_into_module(
-        std::path::Path::new("template_new_auto"), 
-        std::path::Path::new("src/template_new_auto_mod.rs"));
-
+        std::path::Path::new("template_new_auto"),
+        std::path::Path::new("src/template_new_auto_mod.rs"),
+    );
+
     copy_files_to_strings_mod::copy_folder_files_into_module(
-        std::path::Path::new("template_new_cli"), 
-        std::path::Path::new("src/template_new_cli_mod.rs"));
+        std::path::Path::new("template_new_cli"),
+        std::path::Path::new("src/template_new_cli_mod.rs"),
+    );
 
     copy_files_to_strings_mod::copy_folder_files_into_module(
-        std::path::Path::new("template_new_wasm"), 
-        std::path::Path::new("src/template_new_wasm_mod.rs"));
+        std::path::Path::new("template_new_wasm"),
+        std::path::Path::new("src/template_new_wasm_mod.rs"),
+    );
 
     copy_files_to_strings_mod::copy_folder_files_into_module(
-        std::path::Path::new("template_new_pwa_wasm"), 
-        std::path::Path::new("src/template_new_pwa_wasm_mod.rs"));
+        std::path::Path::new("template_new_pwa_wasm"),
+        std::path::Path::new("src/template_new_pwa_wasm_mod.rs"),
+    );
 
     let cargo_toml = cl::CargoToml::read();
     cl::auto_version_increment_semver_or_date();
@@ -185,15 +200,15 @@ fn task_release() {
     cl::run_shell_command(&format!(
         "strip target/release/{package_name}",
         package_name = cargo_toml.package_name()
-    )); 
+    ));
     println!(
         r#"
     {YELLOW}After `cargo auto release`, run the compiled binary, examples and/or tests{RESET}
 {GREEN}./target/release/{package_name} argument{RESET}
     {YELLOW}if ok, then,{RESET}
 {GREEN}cargo auto doc{RESET}
 "#,
-package_name = cargo_toml.package_name(),
+        package_name = cargo_toml.package_name(),
     );
     print_examples_cmd();
 }
@@ -212,11 +227,33 @@ fn task_doc() {
     // Create simple index.html file in docs directory
     cl::run_shell_command(&format!(
         "echo \"<meta http-equiv=\\\"refresh\\\" content=\\\"0; url={}/index.html\\\" />\" > docs/index.html",
-        cargo_toml.package_name().replace("-","_")
+        cargo_toml.package_name().replace("-", "_")
     ));
-    // use tidy HTML to format the html files to be human readable and usable for git diff
-    // TODO: what happens if tidy is not installed on the system?
-    cl::run_shell_command("find . -name '*.html' -type f -print -exec tidy -mq '{}' \\;");
+
+    // region: tidy HTML
+    // The HTML generated by `cargo doc` is ugly and difficult to `git diff`
+    // tidy HTML is a HTML checker and formatter installed on most Linuxes.
+    // If it is not installed run: `sudo apt install -y tidy`
+    // From the bash you can install it inside the podman container like this:
+    // `podman exec --user root rust_dev_vscode_cnt apt install -y tidy`
+    //
+    // First we check if tidy is installed on the system
+    // Run a dummy command and write the std/err output to tidy_warnings.txt.
+    // The command `2>` will overwrite the file and not append like `2>>`.
+    cl::run_shell_command("tidy xxx 2> docs/tidy_warnings.txt");
+    // Check if it contains `command not found`
+    let text = std::fs::read_to_string("docs/tidy_warnings.txt").unwrap();
+    // don't need this file anymore
+    cl::run_shell_command("rm -f docs/tidy_warnings.txt");
+    if !text.contains("command not found") {
+        // Use tidy HTML to format the docs/*.html files to be human readable and usable for git diff.
+        // Options: -m modify file, -q quiet suppress nonessential output, -w wrap at 160,
+        // The warnings and errors are appended to the file docs/tidy_warnings.txt
+        cl::run_shell_command(
+            r#"find ./docs -name '*.html' -type f -print -exec tidy -mq -w 160 '{}' \; >> docs/tidy_warnings.txt 2>&1 "#,
+        );
+    }
+    // endregion: tidy HTML
     cl::run_shell_command("cargo fmt");
     // message to help user with next move
     println!(
@@ -247,7 +284,10 @@ fn task_commit_and_push(arg_2: Option<String>) {
             // separate commit for docs if they changed, to not make a lot of noise in the real commit
             cl::run_shell_command(r#"git add docs && git diff --staged --quiet || git commit -m "update docs" "#);
             // the real commit of code
-            cl::run_shell_command(&format!(r#"git add -A && git diff --staged --quiet || git commit -m "{}" "#, message));
+            cl::run_shell_command(&format!(
+                r#"git add -A && git diff --staged --quiet || git commit -m "{}" "#,
+                message
+            ));
             cl::run_shell_command("git push");
             println!(
                 r#"
@@ -318,7 +358,7 @@ r#"## Changed
         // compress files tar.gz
         let tar_name = format!("{repo_name}-{tag_name_version}-x86_64-unknown-linux-gnu.tar.gz");
         cl::run_shell_command(&format!("tar -zcvf {tar_name} target/release/{repo_name}"));
-        
+
         // upload asset     
         auto_github_upload_asset_to_release(&owner, &repo_name, &release_id, &tar_name).await;
         cl::run_shell_command(&format!("rm {tar_name}"));  

diff --git a/src/main.rs b/src/main.rs
@@ -2,7 +2,7 @@
 //! # cargo-auto  
 //!
 //! **cargo-auto - automation tasks written in Rust language for the build process of Rust projects**  
-//! ***version: 2024.209.128 date: 2024-02-09 author: [bestia.dev](https://bestia.dev) repository: [GitHub](https://github.com/bestia-dev/cargo-auto)***  
+//! ***version: 2024.209.135 date: 2024-02-09 author: [bestia.dev](https://bestia.dev) repository: [GitHub](https://github.com/bestia-dev/cargo-auto)***  
 //!
 //!  ![status](https://img.shields.io/badge/maintained-green)
 //!  ![status](https://img.shields.io/badge/ready_for_use-green)
@@ -15,11 +15,11 @@
 //!  [![Rust](https://github.com/bestia-dev/cargo-auto/workflows/rust_fmt_auto_build_test/badge.svg)](https://github.com/bestia-dev/cargo-auto/)
 //!  ![Hits](https://bestia.dev/webpage_hit_counter/get_svg_image/959103982.svg)
 //!
-//! [![Lines in Rust code](https://img.shields.io/badge/Lines_in_Rust-9181-green.svg)](https://github.com/bestia-dev/cargo-auto/)
-//! [![Lines in Doc comments](https://img.shields.io/badge/Lines_in_Doc_comments-471-blue.svg)](https://github.com/bestia-dev/cargo-auto/)
+//! [![Lines in Rust code](https://img.shields.io/badge/Lines_in_Rust-9179-green.svg)](https://github.com/bestia-dev/cargo-auto/)
+//! [![Lines in Doc comments](https://img.shields.io/badge/Lines_in_Doc_comments-1227-blue.svg)](https://github.com/bestia-dev/cargo-auto/)
 //! [![Lines in Comments](https://img.shields.io/badge/Lines_in_comments-349-purple.svg)](https://github.com/bestia-dev/cargo-auto/)
 //! [![Lines in examples](https://img.shields.io/badge/Lines_in_examples-0-yellow.svg)](https://github.com/bestia-dev/cargo-auto/)
-//! [![Lines in tests](https://img.shields.io/badge/Lines_in_tests-1526-orange.svg)](https://github.com/bestia-dev/cargo-auto/)
+//! [![Lines in tests](https://img.shields.io/badge/Lines_in_tests-1524-orange.svg)](https://github.com/bestia-dev/cargo-auto/)
 //!
 //! Hashtags: #rustlang #tutorial #buildtool #developmenttool #cli  
 //! My projects on GitHub are more like a tutorial than a finished product: [bestia-dev tutorials](https://github.com/bestia-dev/tutorials_rust_wasm).