elaborated on the usage

Release 1.3

.github/workflows/rust_deploy.yml

@@ -4,7 +4,7 @@ on:
     push:
         branches: ["main"]
         paths:
-            - "Cargo.toml"
+            - "./Cargo.toml"
 
 env:
     CARGO_TERM_COLOR: always
@@ -16,7 +16,7 @@ jobs:
         steps:
             - uses: actions/checkout@v4
             - name: Build
-              run: cargo build --verbose
+              run: cargo build --release --bin docki
             - name: Run tests
               run: cargo test --verbose
             - name: Publish to crates.io

Cargo.toml

@@ -1,11 +1,20 @@
 [package]
 name = "docki"
-version = "1.2.3"
+version = "1.3.0"
 edition = "2021"
 description = "cli for building and publishing documentation using asciidoctor"
 license-file = "LICENSE.txt"
 authors = ["Quirin Ecker"]
 exclude = [".gitlab", ".github"]
+default-run = "docki"
+
+[[bin]]
+name = "docki"
+path = "src/main.rs"
+
+[[bin]]
+name = "util"
+path = "src/util.rs"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
@@ -25,3 +34,4 @@ clap_complete = "4.1.4"
 nu-ansi-term = "0.50.3"
 config = { version = "0.15.18", features = ["toml"] }
 serde = "1.0.228"
+toml = "0.9.6"

README.md

@@ -1,9 +1,5 @@
 # Docki
 
-> [!NOTE]
-> This project is under renovations. It can be used, but it might not be completely stable yet.
-
-
 ## Preview
 
 ![screencast](.github/assets/screencast.gif)
@@ -12,8 +8,15 @@ Docki is cli for converting asciidoctor files into html files.
 
 ## Usage
 
+Docki must be run in a directory with the following structure
+
+![docki directory structure](.github/assets/directory_structure.png)
+
+1. Will be converted into asciidoc format
+2. Will be converted into asciidocs slides
+
 > [!NOTE]
-> This works in a directory with a directory called `docs`, which contains the asciidoctor documentation.
+> The input directory can be defined either with a cli argument or the config file. Default is `./docs`
 
 ### Building the documentation
 
@@ -21,7 +24,7 @@ Docki is cli for converting asciidoctor files into html files.
 docki build
 ```
 
-### Serving the documentation on a live server
+### Serving the documentation with a live server
 
 ```shell
 docki serve
@@ -114,7 +117,7 @@ home.packages = with pkgs; [
 
 ## Configuration
 
-You can configure some of the cli arguments with a config file. It is always located relatively to the current directory under `./docki.config.toml`. Available options and their defaults can be found in the [config.rs](src/app/config/config.rs) file. CLI arguments with the same names as in the config usually have also the same default values.
+You can configure some of the cli arguments with a config file. It is always located relatively to the current directory under `./docki.config.toml`. Available options and their defaults can be found in the [docki.config.toml](config/docki.config.toml) file. CLI arguments with the same names as in the config usually have also the same default values. As a fallback you can also use the [config.rs](src/app/config/config.rs) file for reference.
 
 ## Development
 

config/docki.config.toml

@@ -0,0 +1,4 @@
+port = 8080
+input_dir = "./docs"
+offline_reveal = false
+output_dir = "./dist"

flake.nix

@@ -64,6 +64,11 @@
             libiconv
             makeWrapper
           ];
+          binaries = [ "docki" ];
+          # only including the main binary in build
+          # There is no better option at the time of writing this
+          # https://github.com/nix-community/naersk/issues/127
+          copyBinsFilter = ''select(.reason == "compiler-artifact" and .executable != null and .profile.test == false and .target.name == "docki")'';
           postInstall = ''
             mkdir -p $out/share/bash-completion/completions
             mkdir -p $out/share/zsh/site-functions

res/test/docki.config.toml

@@ -1,3 +1,3 @@
-docs_dir = "./docs"
+docs_dir = "./asciidocs"
 port = 6969
 offline_reveal = false

src/app/build/asciidoctor.rs

@@ -1,6 +1,8 @@
 use regex::Regex;
 use std::process;
 
+use crate::app::config::config::Config;
+
 fn exec_command(command: &mut process::Command) -> Result<(), String> {
     let result = command.output();
 
@@ -32,11 +34,14 @@ fn asciidoctor_docs(in_path: &str, out_path: &str) -> process::Command {
     return command;
 }
 
-fn asciidoctor_slides(in_path: &str, out_path: &str, offline_reveal: bool) -> process::Command {
+fn asciidoctor_slides(in_path: &str, out_path: &str, config: &Config) -> process::Command {
     let mut command = process::Command::new(format!("asciidoctor-revealjs"));
     let out_dir = parent_path(out_path);
-    let revealjs_path = if offline_reveal {
-        path_between(out_dir.to_string(), "./dist/slides/revealjs".to_string())
+    let revealjs_path = if config.offline_reveal {
+        path_between(
+            out_dir.to_string(),
+            format!("{}/slides/revealjs", config.output_dir),
+        )
     } else {
         "https://cdn.jsdelivr.net/npm/reveal.js@5.2.1".to_string()
     };
@@ -104,13 +109,13 @@ pub fn matching_from_start(from_segments: &Vec<String>, to_segments: &Vec<String
     return from_segments.len();
 }
 
-pub fn build_doc(in_path: &str, out_path: &str) -> Result<(), String> {
+pub fn build_doc(in_path: &str, out_path: &str, _: &Config) -> Result<(), String> {
     let mut command = asciidoctor_docs(in_path, out_path);
     return exec_command(&mut command);
 }
 
-pub fn build_slide(in_path: &str, out_path: &str, offline_reveal: bool) -> Result<(), String> {
-    let mut command = asciidoctor_slides(in_path, out_path, offline_reveal);
+pub fn build_slide(in_path: &str, out_path: &str, config: &Config) -> Result<(), String> {
+    let mut command = asciidoctor_slides(in_path, out_path, config);
     return exec_command(&mut command);
 }
 

src/app/build/mod.rs

@@ -1 +1,150 @@
 pub mod asciidoctor;
+
+use std::{
+    fs, io::Cursor, path::PathBuf
+};
+
+use crate::app::{
+    build::{asciidoctor::build_slide, asciidoctor::build_doc}, config::config::Config, fs_util::{self, create_dir_recursive}, log::display_status
+};
+
+pub struct DockiBuilder<'a> {
+    progress: usize,
+    goal: usize,
+	config: &'a Config
+}
+
+impl <'a> DockiBuilder <'a> {
+    pub fn new(config: &'a Config) -> Self {
+        return Self {
+            progress: 0,
+            goal: 0,
+			config: config
+        };
+    }
+
+
+	///
+	/// Prepares everything for building the documentation
+	///
+	/// 1. Checks if the input directory exists and if not, returns an error
+	/// 2. When offline_reveal is set to true, it downloads revealjs. When it fails, it returns an error
+    pub async fn prepare(&self) -> Result<(), String> {
+        if !fs_util::directory_exists(&self.config.input_dir) {
+            return Err(
+                "docs directory does not exist it. Create it or use the template".to_string(),
+            );
+        }
+
+		if !self.config.offline_reveal {
+			return Ok(())
+		}
+
+        let reveal_version = "5.2.1";
+        let target = format!("https://github.com/hakimel/reveal.js/archive/{reveal_version}.zip");
+
+        create_dir_recursive(format!("{}/slides", self.config.input_dir).as_str());
+
+		reqwest::get(target.clone()).await.unwrap();
+        let Ok(response) = reqwest::get(target).await else {
+            return Err("could not downlaod revealjs".to_string())
+        };
+
+        let Ok(bytes) = response.bytes().await else {
+            return Err("could not extract bytes".to_string())
+        };
+
+        let out = PathBuf::from(format!("{}/slides/revealjs", self.config.input_dir));
+
+        if zip_extract::extract(Cursor::new(bytes), &out, true).is_err() {
+            return Err("could not write extracted archive to disk".to_string());
+        }
+
+        return Ok(());
+    }
+
+
+	/// Builds all files in the input directory with a pretty output
+    pub fn build_docs(&mut self) -> Result<(), String> {
+        let result = fs_util::fetch_paths_recursive(&self.config.input_dir);
+        let Ok(paths) = result else {
+            return Err(result.unwrap_err())
+        };
+
+		let reveal_dir = format!("{}/slides/revealjs", self.config.input_dir);
+		let paths = paths.into_iter()
+			.filter(|path| self.config.offline_reveal || !path.starts_with(reveal_dir.as_str()))
+			.collect::<Vec<String>>();
+
+		self.goal = paths.len();
+
+        for (index, in_path) in paths.iter().enumerate() {
+            self.progress = index + 1;
+            let result = self.build_file(&in_path);
+
+            match result {
+                DockiBuildResult::Err(err) => {
+                    self.display_building_status("Error", &in_path, "");
+                    println!("{}", err)
+                },
+                DockiBuildResult::Copy(out_path) => self.display_building_status("Copy", &in_path, &out_path),
+                DockiBuildResult::Slide(out_path) => self.display_building_status("Slide", &in_path, &out_path),
+                DockiBuildResult::Doc(out_path) => self.display_building_status("Doc", &in_path, &out_path),
+            }
+        }
+
+        return Ok(());
+    }
+
+
+	/// Builds a single file without a pretty output
+	pub fn build_file(&self, path: &str) -> DockiBuildResult {
+		let out_path = path.replace(&self.config.input_dir, &self.config.output_dir);
+		let convert_out_path = out_path.replace(".adoc", ".html");
+
+		if path.starts_with(format!("{}/slides/", &self.config.input_dir).as_str()) && path.ends_with(".adoc") {
+			if let Err(err) = build_slide(&path, &convert_out_path, self.config) {
+				return DockiBuildResult::Err(err);
+			}
+
+			DockiBuildResult::Slide(convert_out_path)
+		} else if path.ends_with(".adoc") {
+			if let Err(err) = build_doc(&path, &convert_out_path, self.config) {
+				return DockiBuildResult::Err(err);
+			}
+
+			DockiBuildResult::Doc(convert_out_path)
+		} else {
+			if let Err(err) = Self::copy(&path, &out_path) {
+				return DockiBuildResult::Err(err);
+			}
+
+			DockiBuildResult::Copy(out_path)
+		}
+	}
+
+	fn copy(in_path: &str, out_path: &str) -> Result<(), String> {
+		fs_util::create_parent_dir_recursive(out_path);
+
+		if let Err(err) = fs::copy(in_path, out_path) {
+			return Err(err.to_string());
+		}
+
+		Ok(())
+	}
+
+    fn display_building_status(&self, status_type: &str, in_path: &str, out_path: &str) -> () {
+        let progress_str = format!("{} / {}", self.progress, self.goal);
+        display_status(&progress_str, status_type, in_path, out_path);
+    }
+
+}
+
+
+/// Used for the Result of build_file. This way it is known what the builder did
+pub enum DockiBuildResult {
+    Slide(String),
+    Doc(String),
+    Copy(String),
+    Err(String),
+}

src/app/commands/build.rs

@@ -1,10 +1,10 @@
 use crate::app::config::config::Config;
 
-use super::executions::build_execution::BuildExecution;
+use crate::app::build::DockiBuilder;
 
 pub async fn build(config: &Config) -> () {
-    let mut build_execution = BuildExecution::new(config);
+    let mut builder = DockiBuilder::new(config);
 
-	build_execution.prepare().await.expect("could not prepare for build");
-    build_execution.build_dir().expect("build failed")
+	builder.prepare().await.expect("could not prepare for build");
+    builder.build_docs().expect("build failed")
 }

src/app/commands/executions/build_execution.rs

@@ -1,137 +0,0 @@
-use std::{
-    fs, io::Cursor, path::PathBuf
-};
-
-use crate::app::{
-    build::{asciidoctor::build_slide, asciidoctor::build_doc}, config::config::Config, fs_util::{self, create_dir_recursive}, log::display_status
-};
-
-pub struct BuildExecution<'a> {
-    progress: usize,
-    goal: usize,
-	config: &'a Config
-}
-
-impl <'a> BuildExecution <'a> {
-    pub fn new(config: &'a Config) -> Self {
-        return Self {
-            progress: 0,
-            goal: 0,
-			config: config
-        };
-    }
-
-    pub async fn prepare(&self) -> Result<(), String> {
-        if !fs_util::directory_exists(&self.config.input_dir) {
-            return Err(
-                "docs directory does not exist it. Create it or use the template".to_string(),
-            );
-        }
-
-		if !self.config.offline_reveal {
-			return Ok(())
-		}
-
-        let reveal_version = "5.2.1";
-        let target = format!("https://github.com/hakimel/reveal.js/archive/{reveal_version}.zip");
-
-        create_dir_recursive(format!("{}/slides", self.config.input_dir).as_str());
-
-		reqwest::get(target.clone()).await.unwrap();
-        let Ok(response) = reqwest::get(target).await else {
-            return Err("could not downlaod revealjs".to_string())
-        };
-
-        let Ok(bytes) = response.bytes().await else {
-            return Err("could not extract bytes".to_string())
-        };
-
-        let out = PathBuf::from(format!("{}/slides/revealjs", self.config.input_dir));
-
-        if zip_extract::extract(Cursor::new(bytes), &out, true).is_err() {
-            return Err("could not write extracted archive to disk".to_string());
-        }
-
-        return Ok(());
-    }
-
-    pub fn build_dir(&mut self) -> Result<(), String> {
-        let result = fs_util::fetch_paths_recursive(&self.config.input_dir);
-        let Ok(paths) = result else {
-            return Err(result.unwrap_err())
-        };
-
-		let reveal_dir = format!("{}/slides/revealjs", self.config.input_dir);
-		let paths = paths.into_iter()
-			.filter(|path| self.config.offline_reveal || !path.starts_with(reveal_dir.as_str()))
-			.collect::<Vec<String>>();
-
-		self.goal = paths.len();
-
-        for (index, in_path) in paths.iter().enumerate() {
-            self.progress = index + 1;
-            let result = self.build_file(&in_path);
-
-            match result {
-                DockiBuildResult::Err(err) => {
-                    self.display_building_status("Error", &in_path, "");
-                    println!("{}", err)
-                },
-                DockiBuildResult::Copy(out_path) => self.display_building_status("Copy", &in_path, &out_path),
-                DockiBuildResult::Slide(out_path) => self.display_building_status("Slide", &in_path, &out_path),
-                DockiBuildResult::Doc(out_path) => self.display_building_status("Doc", &in_path, &out_path),
-            }
-        }
-
-        return Ok(());
-    }
-
-	pub fn build_file(&mut self, path: &str) -> DockiBuildResult {
-		let out_path = path.replace(&self.config.input_dir, "./dist");
-		let convert_out_path = out_path.replace(".adoc", ".html");
-
-		if path.starts_with(format!("{}/slides/", &self.config.input_dir).as_str()) && path.ends_with(".adoc") {
-			if let Err(err) = build_slide(&path, &convert_out_path, self.config.offline_reveal) {
-				return DockiBuildResult::Err(err);
-			}
-
-			DockiBuildResult::Slide(convert_out_path)
-		} else if path.ends_with(".adoc") {
-			if let Err(err) = build_doc(&path, &convert_out_path) {
-				return DockiBuildResult::Err(err);
-			}
-
-			DockiBuildResult::Doc(convert_out_path)
-		} else {
-			if let Err(err) = Self::copy(&path, &out_path) {
-				return DockiBuildResult::Err(err);
-			}
-
-			DockiBuildResult::Copy(out_path)
-		}
-	}
-
-	fn copy(in_path: &str, out_path: &str) -> Result<(), String> {
-		fs_util::create_parent_dir_recursive(out_path);
-
-		if let Err(err) = fs::copy(in_path, out_path) {
-			return Err(err.to_string());
-		}
-
-		Ok(())
-	}
-
-    fn display_building_status(&self, status_type: &str, in_path: &str, out_path: &str) -> () {
-        let progress_str = format!("{} / {}", self.progress, self.goal);
-        display_status(&progress_str, status_type, in_path, out_path);
-    }
-
-}
-
-
-pub enum DockiBuildResult {
-    Slide(String),
-    Doc(String),
-    Copy(String),
-    Err(String),
-}

src/app/commands/executions/mod.rs

@@ -1 +0,0 @@
-pub mod build_execution;

src/app/commands/mod.rs

@@ -1,6 +1,5 @@
 pub mod build;
 pub mod completions;
-pub mod executions;
 pub mod health;
 pub mod install_reveal;
 pub mod serve;

src/app/commands/serve.rs

@@ -7,30 +7,33 @@ use notify::{
 };
 use std::{env, path::Path};
 
-use crate::app::{ commands::executions::build_execution::{self, BuildExecution, DockiBuildResult}, config::config::Config, log::display_status, watcher::watcher};
+use crate::app::watcher::watcher;
+use crate::app::log::display_status;
+use crate::app::config::config::Config;
+use crate::app::build::{DockiBuildResult, DockiBuilder};
 
 pub async fn serve(config: &Config) {
-	let build_execution = BuildExecution::new(config);
-	let mut server = Server::new(build_execution, config);
+	let builder = DockiBuilder::new(config);
+	let mut server = Server::new(builder, config);
 	server.serve().await;
 }
 
 struct Server<'a> {
-	build_execution: BuildExecution<'a>,
+	builder: DockiBuilder<'a>,
 	config: &'a Config,
 }
 
 impl <'a> Server <'a> {
-	pub fn new(build_execution: BuildExecution<'a>, config: &'a Config) -> Self {
+	fn new(builder: DockiBuilder<'a>, config: &'a Config) -> Self {
 		return Self {
-			build_execution: build_execution,
+			builder,
 			config: config
 		}
 	}
 
 	async fn serve(&mut self) {
-		self.build_execution.prepare().await.expect("could not prepare for build");
-		self.build_execution.build_dir().expect("build failed");
+		self.builder.prepare().await.expect("could not prepare for build");
+		self.builder.build_docs().expect("build failed");
 		tokio::join!(self.start_server(), self.watch_and_build());
 	}
 
@@ -43,18 +46,18 @@ impl <'a> Server <'a> {
 			hyperlink
 		);
 
-		let Ok(()) = listen("localhost", self.config.port, "./dist").await else {
+		let Ok(()) = listen("localhost", self.config.port, self.config.output_dir.clone()).await else {
 			panic!("could not start server")
 		};
 	}
 
-	async fn watch_and_build(&mut self) {
+	async fn watch_and_build(&self) {
 		self.watch()
 			.await
 			.expect("something went wrong")
 	}
 
-	async fn watch(&mut self) -> notify::Result<()> {
+	async fn watch(&self) -> notify::Result<()> {
 		let path = Path::new(&self.config.input_dir);
 		let (mut watcher, mut rx) = watcher()?;
 
@@ -69,42 +72,36 @@ impl <'a> Server <'a> {
 
 	}
 
-	fn file_change(&mut self, event: Event) {
+	fn file_change(&self, event: Event) {
 		match event.kind {
-			EventKind::Modify(ModifyKind::Data(_)) => self.build_file(event.paths),
+			EventKind::Modify(ModifyKind::Data(_)) => self.build_valid_files(event.paths),
 			_ => (),
 		}
 	}
 
-	fn build_file(&mut self, paths: Vec<std::path::PathBuf>) {
+	fn build_valid_files(&self, paths: Vec<std::path::PathBuf>) {
 		let invalid_path_message = "changed path is invalid";
 		let in_path = paths
 			.first()
 			.expect(invalid_path_message)
-			.strip_prefix(&current_dir())
+			.strip_prefix(&Self::current_dir())
 			.expect(invalid_path_message)
 			.to_str()
 			.expect(invalid_path_message);
 
 		let in_path = format!("./{}", in_path);
-		let result = self.build_execution.build_file(&in_path);
+		let result = self.builder.build_file(&in_path);
 
 		match result {
-			DockiBuildResult::Slide(out_path) => display_rebuilding_status("Slide", &in_path, &out_path),
-			DockiBuildResult::Doc(out_path) => display_rebuilding_status("Doc", &in_path, &out_path),
-			DockiBuildResult::Copy(out_path) => display_rebuilding_status("Copy", &in_path, &out_path),
+			DockiBuildResult::Slide(out_path) => Self::display_rebuilding_status("Slide", &in_path, &out_path),
+			DockiBuildResult::Doc(out_path) => Self::display_rebuilding_status("Doc", &in_path, &out_path),
+			DockiBuildResult::Copy(out_path) => Self::display_rebuilding_status("Copy", &in_path, &out_path),
 			DockiBuildResult::Err(err) => {
-				display_rebuilding_status("Error", &in_path, "");
+				Self::display_rebuilding_status("Error", &in_path, "");
 				println!("{}", err);
 			},
 		}
 	}
-}
-
-
-
-
-
 
 	fn display_rebuilding_status(context: &str, in_path: &str, out_path: &str) {
 		display_status("Rebuildng", context, in_path, out_path)
@@ -119,4 +116,6 @@ fn current_dir() -> String {
 				.expect(err_message),
 		);
 	}
+}
+
 

src/app/config/arguments.rs

@@ -22,6 +22,11 @@ pub struct Args {
     /// The directory where the documentation will be built
     #[arg(short, long, global = true)]
     pub output_dir: Option<String>,
+
+	/// When set to true, docki will download revealjs before building the documentation.
+	/// Otherwise it will use the cdn for revealjs
+	#[arg(long, global = true)]
+	pub offline_reveal: bool,
 }
 
 #[derive(Subcommand)]
@@ -33,13 +38,8 @@ pub enum ShellArg {
 
 #[derive(Subcommand)]
 pub enum CommandArg {
-    /// Builds the documentation into a dist folder
-    Build {
-        /// When set to true, docki will download revealjs before building the documentation.
-        /// Otherwise it will use the cdn for revealjs
-        #[arg(short, long)]
-        offline_reveal: bool,
-    },
+    /// Builds the documentation into the specified output_dir
+    Build,
     /// Checks if everything required for docki is installed
     Health,
     /// Deprecated: Helper command for installing asciidoctor-reveal-js

src/app/config/config.rs

@@ -1,14 +1,14 @@
-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
 
 use crate::app::config::arguments::CommandArg;
 
-#[derive(Deserialize, Debug)]
+#[derive(Deserialize, Debug, Serialize)]
 #[serde(default)]
 pub struct Config {
     pub port: u16,
     pub input_dir: String,
     pub offline_reveal: bool,
-	pub output_dir: String
+    pub output_dir: String,
 }
 
 impl Config {
@@ -27,13 +27,7 @@ impl Config {
             },
             input_dir: args.input_dir.clone().unwrap_or(self.input_dir),
             output_dir: args.output_dir.clone().unwrap_or(self.output_dir),
-            offline_reveal: {
-                if let CommandArg::Build { offline_reveal } = args.command {
-                    offline_reveal
-                } else {
-                    self.offline_reveal
-                }
-            },
+            offline_reveal: args.offline_reveal || self.offline_reveal,
         }
     }
 }

src/app/mod.rs

@@ -3,7 +3,7 @@ pub mod build;
 pub mod fs_util;
 pub mod watcher;
 pub mod log;
-mod config;
+pub mod config;
 
 use std::env;
 

src/test/fs_util.rs

@@ -5,5 +5,5 @@ fn test_fetch_asciidoctor_paths_recursive() {
     let paths = fs_util::fetch_paths_recursive("res/test/docs").unwrap();
     let len = paths.len();
     dbg!(paths);
-    assert_eq!(len, 6);
+    assert_eq!(len, 2);
 }

src/util.rs

@@ -0,0 +1,34 @@
+mod app;
+
+use std::{fs::File, io::Write};
+
+use app::config::config::Config;
+use clap::{Parser, Subcommand};
+
+#[derive(Parser)]
+pub struct Args {
+    #[command(subcommand)]
+    pub command: CommandArg,
+}
+
+#[derive(Subcommand)]
+pub enum CommandArg {
+    /// Generates a default docki.config.toml
+    GenerateDefaultConfig,
+}
+
+fn main() {
+    let args = Args::parse();
+    match args.command {
+        CommandArg::GenerateDefaultConfig => generate_default_config(),
+    }
+}
+
+fn generate_default_config() {
+    let default_config = Config::default();
+    let target_file = "config/docki.config.toml";
+	let mut file = File::create(target_file).unwrap();
+    let output = toml::to_string_pretty(&default_config).unwrap();
+
+	file.write_all(output.as_bytes()).unwrap();
+}