small quality of life changes

.github/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contribution Guide
+
+## Guidelines
+
+* All changes ideally must be first suggested in an issue and then contributed via Pull Requests.
+* If your proposed change warrants a test, please add one.
+* If you're changing API behaviour, please update the docstrings.
+* Please have a look at the various linters being used and make sure to run them periodically and **especially** before pushing.
+* Every PR must pass all tests in CI.
+
+## Advice for the developer
+
+* We have a `.pre-commit-config.yaml` file that you can use for general code sanitization.

.github/workflows/docs.yml

@@ -4,9 +4,6 @@ on:
     push:
         branches: [main]
 
-    pull_request:
-        branches: [main]
-
 permissions:
     contents: read
     pages: write

src/config_handler.rs

@@ -1,10 +1,15 @@
+//! parse and process configuration
 use std::{path::PathBuf, process::exit};
 
 use rascii_art::RenderOptions;
 use serde_derive::Deserialize;
 
 use crate::util::path_utils::get_path;
 
+/// core struct to store data parsed from the configuration file
+///
+/// NOTE: Notice how `ascii` and `image` are an [`Option`] i.e. one can provide
+/// either or None
 #[derive(Deserialize, Debug)]
 pub struct Config {
     pub ascii: Option<AsciiConfig>,
@@ -19,6 +24,27 @@ impl Config {
     ///
     /// # Returns
     /// * `Result<Self, toml::de::Error>` - The parsed configuration or an error.
+    ///
+    /// # Examples
+    /// Let's say your configuration file looks like this
+    ///
+    /// ```toml
+    /// [ascii]
+    /// path="ascii"
+    /// ```
+    /// i.e. you want to show some ASCII art saved in some file at path `ascii`
+    ///
+    /// You can access the path as follows
+    ///
+    /// ```
+    /// use std::path::PathBuf;
+    /// use symfetch::config_handler::Config;
+    ///
+    /// let config = Config::new(&PathBuf::from("tests/only_ascii.toml")).unwrap();
+    /// let ascii_config = &config.ascii.as_ref().unwrap();
+    ///
+    /// assert_eq!(&ascii_config.path, &PathBuf::from("ascii"));
+    /// ```
     pub fn new(config_path: &PathBuf) -> Result<Self, toml::de::Error> {
         let contents = match std::fs::read_to_string(config_path) {
             Ok(contents) => contents,
@@ -56,6 +82,7 @@ impl Config {
     }
 }
 
+/// store parsed information from the "\[ascii\]" table
 #[derive(Deserialize, Debug)]
 pub struct AsciiConfig {
     pub path: PathBuf,
@@ -70,26 +97,26 @@ impl AsciiConfig {
     ///
     /// # Returns
     /// * `AsciiConfig` - The new `AsciiConfig` instance.
-    ///
-    /// ```
-    /// use std::{env, path::PathBuf};
-    /// use symfetch::config_handler::AsciiConfig;
-    ///
-    /// let ascii_path = PathBuf::from("~/.config/symfetch/ascii");
-    /// let ascii_config = AsciiConfig::new(ascii_path);
-    /// ```
     pub fn new(path: PathBuf) -> Self {
         let path = get_path(&path);
         AsciiConfig { path }
     }
 }
 
+/// store parsed information from the "\[image\]" table
 #[allow(dead_code)]
 #[derive(Deserialize, Debug)]
 pub struct ImageConfig {
+    /// The path to the image file.
     pub path: PathBuf,
+
+    /// width parameter for [`RenderOptions`]
     pub width: Option<u32>,
+
+    /// height parameter for [`RenderOptions`]
     pub height: Option<u32>,
+
+    /// colored parameter for [`RenderOptions`]
     pub colored: Option<bool>,
 }
 
@@ -125,6 +152,10 @@ impl ImageConfig {
         }
     }
 
+    /// create [`RenderOptions`] for calling `rascii_art::render_image`
+    ///
+    /// if while creating a [`ImageConfig`] instance, the `width`, `height` and `colored`
+    /// parameters are not provided, the default values of 100, 100 and false are used.
     pub fn get_render_options(&self) -> RenderOptions<'static> {
         let colored = self.colored.unwrap_or(false);
 

src/data.rs

@@ -1,3 +1,4 @@
+//! the main engine
 use std::io;
 
 use image::io::Reader as ImageReader;
@@ -6,8 +7,10 @@ use rascii_art::render_image;
 use crate::config_handler::Config;
 use crate::util::path_utils::get_path;
 
+/// holds information about config (+ system data)
 #[derive(Debug)]
 pub struct Data {
+    /// parsed information from config
     pub config: Config,
 }
 
@@ -16,6 +19,7 @@ impl Data {
         Self { config }
     }
 
+    /// If ASCII configuration is provided, write to stdout
     pub fn render_ascii(&self) {
         if let Some(ascii_config) = &self.config.ascii {
             let ascii_content = std::fs::read_to_string(get_path(&ascii_config.path)).unwrap();
@@ -25,6 +29,9 @@ impl Data {
         }
     }
 
+    /// If image configuration is provided, render image to stdout
+    ///
+    /// NOTE: uses [`rascii_art::render_image`]
     pub fn render_image(&self) {
         if let Some(image_config) = &self.config.image {
             let image_path = get_path(&image_config.path);

src/lib.rs

@@ -1,3 +1,45 @@
+//! symfetch
+//!
+//! ## Usage
+//!
+//! You can run the executable by simply calling the symfetch cmd.
+//!
+//! ```bash
+//! symfetch
+//! ```
+//!
+//! `symfetch` by default looks for a config file in `~/.config/symfetch.toml`,
+//! if you want to place your config file somewhere else you can pass that path using the `-c` or `--config` argument.
+//!
+//! For example,
+//!
+//! ```bash
+//! symfetch -c ~/symfetch.toml
+//! ```
+//!
+//! ## Configuration
+//!
+//! We use toml for configuring `symfetch`. The main configuration you need to specify is whether to use
+//! an ASCII art or some image as the graphic. Both these option requires you to specify a path value with a
+//! `[ascii]` or a `[image]` table. For instance
+//!
+//! ASCII only configuration file
+//!
+//! ```toml
+//! [ascii]
+//! path="ascii"
+//! ```
+//!
+//! Image only configuration file
+//!
+//! ```toml
+//! [image]
+//! path="image"
+//! ```
+//!
+//! ## Brought to you by
+//!
+//! ![](https://github.com/SymmetrySyndicate/.github/blob/main/assets/banner/twitter_banner.png?raw=true)
 pub mod config_handler;
 pub mod data;
 pub mod util;

src/util/mod.rs

@@ -1 +1,2 @@
+//! Collection of Utility Class and Functions
 pub mod path_utils;

src/util/path_utils.rs

@@ -3,24 +3,24 @@ use std::{
     path::{Path, PathBuf},
 };
 
-/// Returns the path to the ASCII art file.
-///
-/// If the path starts with `~/.config/`, it will be replaced with the user's home directory.
-/// Otherwise, the path will be returned as is.
+/// If the path starts with `~/.config/`, it will be prepended with the user's
+/// home directory. Otherwise, the path will be returned as is.
 ///
 /// # Arguments
-/// * `path` - The path to the ASCII art file.
+/// * `path` - path to sanitize
 ///
 /// # Returns
-/// * `PathBuf` - The path to the ASCII art file.
+/// * `PathBuf` - sanitized path
 ///
 /// ```
 /// use std::{env, path::PathBuf};
 /// use symfetch::util::path_utils::get_path;
 ///
+/// // user might provide something like this
 /// let ascii_path = PathBuf::from("~/.config/symfetch/ascii");
 /// let ascii_path = get_path(&ascii_path);
 ///
+/// // what we want
 /// let home = PathBuf::from(env::var("HOME").unwrap());
 /// let path = home.join(".config/symfetch/ascii");
 /// assert_eq!(ascii_path, path);

tests/only_image.toml

@@ -0,0 +1,2 @@
+[image]
+path = "image"

tests/test_config.rs

@@ -4,7 +4,7 @@ use symfetch::config_handler::Config;
 
 #[test]
 fn test_config_init() {
-    let config = Config::new(&PathBuf::from("tests/test_symfetch.toml")).unwrap();
+    let config = Config::new(&PathBuf::from("tests/only_ascii.toml")).unwrap();
     let test_ascii_path = PathBuf::from("ascii");
 
     let ascii_config = config.ascii.as_ref().unwrap();