From eaea09fea2ab16454b87c02dfcbf513e97b95974 Mon Sep 17 00:00:00 2001 From: Saurav Maheshkar Date: Wed, 9 Apr 2025 18:47:55 +0100 Subject: [PATCH 1/3] docs: update docstrings --- src/config_handler.rs | 47 +++++++++++++++---- src/data.rs | 7 +++ src/lib.rs | 42 +++++++++++++++++ src/util/mod.rs | 1 + src/util/path_utils.rs | 12 ++--- tests/{test_symfetch.toml => only_ascii.toml} | 0 tests/only_image.toml | 2 + tests/test_config.rs | 2 +- 8 files changed, 98 insertions(+), 15 deletions(-) rename tests/{test_symfetch.toml => only_ascii.toml} (100%) create mode 100644 tests/only_image.toml diff --git a/src/config_handler.rs b/src/config_handler.rs index 39652ce..c15f5b9 100644 --- a/src/config_handler.rs +++ b/src/config_handler.rs @@ -1,3 +1,4 @@ +//! parse and process configuration use std::{path::PathBuf, process::exit}; use rascii_art::RenderOptions; @@ -5,6 +6,10 @@ 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, @@ -19,6 +24,27 @@ impl Config { /// /// # Returns /// * `Result` - 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 { 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, + + /// height parameter for [`RenderOptions`] pub height: Option, + + /// colored parameter for [`RenderOptions`] pub colored: Option, } @@ -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); diff --git a/src/data.rs b/src/data.rs index 29fa477..c0bb6fd 100644 --- a/src/data.rs +++ b/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); diff --git a/src/lib.rs b/src/lib.rs index 8563af2..daaa50f 100644 --- a/src/lib.rs +++ b/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; diff --git a/src/util/mod.rs b/src/util/mod.rs index adbdcef..dbbd7fb 100644 --- a/src/util/mod.rs +++ b/src/util/mod.rs @@ -1 +1,2 @@ +//! Collection of Utility Class and Functions pub mod path_utils; diff --git a/src/util/path_utils.rs b/src/util/path_utils.rs index 486e486..1cfa3bc 100644 --- a/src/util/path_utils.rs +++ b/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); diff --git a/tests/test_symfetch.toml b/tests/only_ascii.toml similarity index 100% rename from tests/test_symfetch.toml rename to tests/only_ascii.toml diff --git a/tests/only_image.toml b/tests/only_image.toml new file mode 100644 index 0000000..c1a4813 --- /dev/null +++ b/tests/only_image.toml @@ -0,0 +1,2 @@ +[image] +path = "image" diff --git a/tests/test_config.rs b/tests/test_config.rs index 7c5902a..0e816e4 100644 --- a/tests/test_config.rs +++ b/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(); From 3c82382f2663e315a5f01e5409c8fe2d4af69516 Mon Sep 17 00:00:00 2001 From: Saurav Maheshkar Date: Wed, 9 Apr 2025 18:48:11 +0100 Subject: [PATCH 2/3] gh: add contributing guideline --- .github/CONTRIBUTING.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .github/CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..e25cf0b --- /dev/null +++ b/.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. From 4ce9f618543adb1eabf1c65e260b5ee962f4687f Mon Sep 17 00:00:00 2001 From: Saurav Maheshkar Date: Wed, 9 Apr 2025 18:53:56 +0100 Subject: [PATCH 3/3] fix(ci): only push docs from main --- .github/workflows/docs.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index bcf54a6..57136fb 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,9 +4,6 @@ on: push: branches: [main] - pull_request: - branches: [main] - permissions: contents: read pages: write