feat(cli.yml): Can provide a custom template for html documentation

BREAKING CHANGE: - --html => --location - --template added - Improved error handling on invalid paths

Author: dustinknopoff

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bashdoc"
-version = "0.4.5"
+version = "0.4.6"
 authors = ["Dustin Knopoff <dustinknopoff@gmail.com>"]
 description = """
 A tool for generating documentation/help menu for user defined bash functions.
@@ -23,10 +23,10 @@ dirs = "1.0.4"
 clap = {version = "2.32", features = ["yaml"]}
 glob = "0.2"
 rayon = "1.0.3"
-serde_derive = "1.0.80"
-serde = "1.0.80"
+serde_derive = "1.0.82"
+serde = "1.0.82"
 serde_json = "1.0.33"
-toml = "0.4.8"
+toml = "0.4.10"
 nom = "4.1.1"
 handlebars = "1.1.0"
 notify = "4.0.6"

cli.yml

@@ -1,7 +1,7 @@
 about: 'Creates a "javadoc" like structure for bash. See github repo github.com/dustinknopoff/bashdoc for information on formatting.'
 author: "Dustin Knopoff <dustinknopoff@gmail.com>"
 name: bashdoc
-version: "0.4.0"
+version: "0.4.6"
 args:
  - color:
  help: "toggles color"
@@ -21,15 +21,22 @@ args:
  short: j
  takes_value: true
  value_name: FILE
- - html:
- help: output html documentation
- short: h
- long: html
- takes_value: true
  - watch:
  help: continuously update on change
  short: w
  long: watch
+ - location:
+ short: l
+ long: location
+ help: location to save HTML
+ takes_value: true
+ required: true
+ - template:
+ short: t
+ long: template
+ help: .hbs template to use for generation of documentation
+ takes_value: true
+ requires: location
 subcommands:
  - override:
  about: override the delimiters

src/docs.rs

@@ -8,13 +8,7 @@ use nom::*;
 use nom_locate::{position, LocatedSpan};
 use rayon::prelude::*;
 use serde_derive::*;
-use std::collections::HashMap;
-use std::env;
-use std::fs;
-use std::fs::File;
-use std::io::prelude::*;
-use std::path::Path;
-
+use std::{collections::HashMap, env, fs, fs::File, io::prelude::*, path::Path, process::exit};
 type Span<'a> = LocatedSpan<CompleteStr<'a>>;
 
 /// Represents a simple Key, Value pair
@@ -198,7 +192,13 @@ fn get_strings_from_file<'a>(p: &Path, delims: Delimiters) -> Vec<Extracted<'a>>
  // println!("{:#?}", used);
  let result = parse_strings_from_file(Span::new(CompleteStr(used)), delims);
  // println!("{:#?}", result);
- result.unwrap().1
+ match result {
+ Ok(r) => r.1,
+ Err(e) => {
+ println!("Error parsing {}", p.display());
+ exit(1);
+ },
+ }
 }
 
 /// Given a `Vec<str>` make a `DocFile`
@@ -345,21 +345,41 @@ pub fn write_json(docstrings: &[DocFile], file_name: &str) {
  .expect("Could not write to file.");
 }
 
-pub fn to_html(docstrings: &[DocFile], dir: &str) {
+pub fn to_html(docstrings: &[DocFile], dir: Option<&str>, template_loc: Option<&str>) {
  for dfile in docstrings {
  let json = to_json(dfile);
  let handlebars = Handlebars::new();
- let mut template = File::open("./static/template.hbs").unwrap();
- let mut output = if dir.len() == 1 {
- File::create(format!("{}.html", dfile.filename).as_str())
- .expect("File cannot be created")
- } else {
- File::create(format!("{}/{}.html", dir, dfile.filename).as_str())
- .expect("File cannot be created")
+ let mut template = match template_loc {
+ Some(m) => match File::open(m) {
+ Ok(o) => o,
+ Err(_) => {
+ println!("Provided path is invalid");
+ exit(1);
+ }
+ },
+ None => File::open("./static/template.hbs").unwrap(),
+ };
+ // let mut template = File::open("./static/template.hbs").unwrap();
+ let mut output = match dir {
+ Some(d) if Path::new(d).is_dir() => {
+ File::create(format!("{}/{}.html", d, dfile.filename).as_str())
+ .expect("File could not be created")
+ }
+ None | Some(_) => {
+ println!("Provided path is invalid");
+ exit(1);
+ }
  };
- handlebars
- .render_template_source_to_write(&mut template, &json, &mut output)
- .unwrap();
+ // let mut output = if dir.len() == 1 {
+ // File::create(format!("{}.html", dfile.filename).as_str())
+ // .expect("File cannot be created")
+ // } else {
+ // File::create(format!("{}/{}.html", dir, dfile.filename).as_str())
+ // .expect("File cannot be created")
+ // };
+ match handlebars
+ .render_template_source_to_write(&mut template, &json, &mut output).expect("Could not generate documentation");
+ 
  }
 }
 
@@ -440,3 +460,80 @@ impl<'a> Delimiters<'a> {
  }
  }
 }
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ mod kv_tests {
+ use super::*;
+ #[test]
+ fn new_kv() {
+ let kv = KV::new(String::from("a"), String::from("b"));
+ assert_eq!(String::from("a"), kv.key);
+ assert_eq!(String::from("b"), kv.value);
+ }
+
+ #[test]
+ fn cmp_kv() {
+ let kv1 = KV::new(String::from("a"), String::from("b"));
+ let kv2 = KV::new(String::from("a"), String::from("b"));
+ let kv = KV::new(String::from("b"), String::from("a"));
+ assert_eq!(kv1, kv2);
+ assert_ne!(kv1, kv);
+ }
+
+ #[test]
+ fn is_as_kv() {
+ let conv = as_kv("type: mp4 or gif");
+ assert_eq!(
+ KV {
+ key: String::from("type"),
+ value: String::from("mp4 or gif")
+ },
+ conv.unwrap()
+ );
+ }
+
+ #[test]
+ fn is_as_kv_white() {
+ let conv = as_kv_whitespace("CTRL-O to open with `open` command,");
+ assert_eq!(
+ KV {
+ key: String::from("CTRL-O"),
+ value: String::from("to open with `open` command,")
+ },
+ conv.unwrap()
+ );
+ }
+ }
+
+ mod docfile_tests {
+ use super::*;
+ #[test]
+ fn test_add() {
+ let mut dfile = DocFile {
+ thedocs: Vec::new(),
+ filename: String::from("zshrc"),
+ };
+ dfile.add(Doc {
+ short_description: String::from("lala"),
+ long_description: String::from("rawr"),
+ descriptors: Vec::new(),
+ params: Vec::new(),
+ returns: Vec::new(),
+ position: 0,
+ });
+ assert_eq!(
+ dfile.thedocs,
+ [Doc {
+ short_description: String::from("lala"),
+ long_description: String::from("rawr"),
+ descriptors: Vec::new(),
+ params: Vec::new(),
+ returns: Vec::new(),
+ position: 0,
+ }]
+ );
+ }
+ }
+}

src/main.rs

@@ -94,8 +94,7 @@ use crate::docs::*;
 use clap::{load_yaml, App, ArgMatches};
 use dirs::home_dir;
 use notify::{DebouncedEvent, RecommendedWatcher, RecursiveMode, Watcher};
-use std::sync::mpsc::channel;
-use std::time::Duration;
+use std::{process::exit, sync::mpsc::channel, time::Duration};
 
 fn main() {
  let yaml = load_yaml!("../cli.yml");
@@ -127,8 +126,12 @@ fn generate<'a>(matches: &'a ArgMatches<'a>) {
  };
  if matches.is_present("json") {
  write_json(&all_em, matches.value_of("json").unwrap());
- } else if matches.is_present("html") {
- to_html(&all_em, matches.value_of("html").unwrap());
+ } else if matches.is_present("location") {
+ to_html(
+ &all_em,
+ matches.value_of("location"),
+ matches.value_of("template"),
+ );
  } else {
  for doc in &all_em {
  if matches.is_present("color") {
@@ -143,7 +146,13 @@ fn generate<'a>(matches: &'a ArgMatches<'a>) {
 fn watcher<'a>(matches: &'a ArgMatches<'a>) {
  generate(matches);
  let (tx, rx) = channel();
- let mut watcher: RecommendedWatcher = Watcher::new(tx, Duration::from_secs(2)).unwrap();
+ let mut watcher: RecommendedWatcher = match Watcher::new(tx, Duration::from_secs(2)) {
+ Ok(d) => d,
+ Err(_) => {
+ println!("Provided path is invalid");
+ exit(1);
+ }
+ };
  let path: String = if cfg!(windows) {
  String::from(matches.value_of("INPUT").unwrap())
  } else {