From 1d37f939c0e00932cdb8aab0f07d73ce589190f6 Mon Sep 17 00:00:00 2001 From: Yiffy Dev Date: Fri, 1 Nov 2024 07:41:49 +0500 Subject: [PATCH] feat!: expose internals with special feature flag, improve related docs --- Cargo.toml | 5 ++++ README.md | 8 +++++++ sabry_build/Cargo.toml | 4 ++++ sabry_build/src/buildmagic.rs | 42 +++++++++++++++++++++++++++++++++ sabry_build/src/lib.rs | 1 - sabry_intrnl/Cargo.toml | 4 ++++ sabry_procmacro/Cargo.toml | 4 ++++ sabry_procmacro_impl/Cargo.toml | 4 ++++ src/lib.rs | 15 +++++++++++- 9 files changed, 85 insertions(+), 2 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 29b8912..94bb5d6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -58,3 +58,8 @@ build = [ net-files = [ "sabry_build/net-files" ] +internals = [] + +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] diff --git a/README.md b/README.md index 9895b02..59ca70d 100644 --- a/README.md +++ b/README.md @@ -636,6 +636,14 @@ This isn't very handy, also isn't strict enough, and is a high-priority subject Not any valid CSS selector is a valid rust identifier. In general this section should not be needed, as you should receive autocompletion from the editor. *However* it doesn't seem to work properly. Check the [wip](#wip) section out. +## Notable feature flags + +**build** - turns on the `sabry::buildy` function, along with the entire `sabry_build` crate where it lives + +**internals** - exposes majority of internal stuff for you to experiment or build own workflow + +**lepty-scoping** - overhauls the scope generation logic, best suitable for the leptos. Check out the [section](#leptos-specials) and an [example](https://github.com/yiffyrusdev/sabry/tree/master/examples/leptos-axum) + ## WIP *(sorted by my own priority)*, "dones" are excluded diff --git a/sabry_build/Cargo.toml b/sabry_build/Cargo.toml index 526a350..400a3a0 100644 --- a/sabry_build/Cargo.toml +++ b/sabry_build/Cargo.toml @@ -19,3 +19,7 @@ walkdir = {version = "^2.5"} [features] net-files = [] + +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] diff --git a/sabry_build/src/buildmagic.rs b/sabry_build/src/buildmagic.rs index f9abcf7..bcff0ef 100644 --- a/sabry_build/src/buildmagic.rs +++ b/sabry_build/src/buildmagic.rs @@ -23,6 +23,29 @@ type ModuleCode = String; type StyleModule = (ModuleName, ModuleCode); type BuilderResult = Result<(), SabryBuildError>; +/// Entry point of sabrys build-magic +/// +/// Example: +/// ``` +/// # use sabry_build::buildmagic::buildy; +/// /* buildy call */ +/// buildy( +/// vec![("mixins.scss".to_string(), "@mixin abc(){}".to_string())] +/// ).expect("Sabry failed to build CSS"); +/// ``` +/// +/// Also you could use style-macros defined anywhere with `sabry::sassy!` procmacro: +/// ```ignore +/// buildy( +/// sabry::usey!( +/// crate1::mixins!(), +/// crate2::tokens!(), +/// crate3::mixins!() +/// ) +/// ).expect("Sabry failed to build CSS"); +/// ``` +/// +/// This function is intended to run at build time, however, you're free to use it however you please pub fn buildy(inline_side_modules: impl IntoIterator) -> BuilderResult { println!("🧙: This is probably the stderr. Something went wrong:"); @@ -49,6 +72,17 @@ pub fn buildy(inline_side_modules: impl IntoIterator) -> Bui Ok(()) } +/// Entrypoint structure of sabrys build-magic. +/// +/// You could construct CSS compilation process by yourself instead of using `buildy` function: +/// ```rust +/// # use sabry_intrnl::config::SabryConfig; +/// # use sabry_build::buildmagic::SabryBuilder; +/// let config = SabryConfig::require().expect("Config didnt load"); +/// let builder = SabryBuilder::new(config); +/// ``` +/// +/// the [buildy] function will just do baseline usage of this structure for you pub struct SabryBuilder { config: SabryConfig, css_compiler: CompilerAdapter, @@ -57,6 +91,14 @@ pub struct SabryBuilder { //🧙 impl SabryBuilder { + /// Construct new [SabryBuilder] from the config + /// + /// You can require [SabryConfig] automatically, with the [Result], by: + /// + /// ``` + /// # use sabry_intrnl::config::SabryConfig; + /// SabryConfig::require().expect("Config didnt load"); + /// ``` pub fn new(config: SabryConfig) -> Self { let css_compiler = CompilerAdapter::new(config.clone()); Self { diff --git a/sabry_build/src/lib.rs b/sabry_build/src/lib.rs index ecac97d..b2d511e 100644 --- a/sabry_build/src/lib.rs +++ b/sabry_build/src/lib.rs @@ -2,4 +2,3 @@ pub mod buildmagic; pub mod filevisit; -pub use buildmagic::*; diff --git a/sabry_intrnl/Cargo.toml b/sabry_intrnl/Cargo.toml index 41c5cbc..e7ff33b 100644 --- a/sabry_intrnl/Cargo.toml +++ b/sabry_intrnl/Cargo.toml @@ -27,3 +27,7 @@ cfg-if = {version = "^1.0"} [features] lepty-scoping = [] + +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] diff --git a/sabry_procmacro/Cargo.toml b/sabry_procmacro/Cargo.toml index 932a3d2..570fccf 100644 --- a/sabry_procmacro/Cargo.toml +++ b/sabry_procmacro/Cargo.toml @@ -15,3 +15,7 @@ proc-macro = true sabry_procmacro_impl = {workspace = true} [features] + +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] diff --git a/sabry_procmacro_impl/Cargo.toml b/sabry_procmacro_impl/Cargo.toml index b170930..a7a1927 100644 --- a/sabry_procmacro_impl/Cargo.toml +++ b/sabry_procmacro_impl/Cargo.toml @@ -18,3 +18,7 @@ raffia = {version = "^0.9"} regex = {version = "^1.11"} [features] + +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] diff --git a/src/lib.rs b/src/lib.rs index 71317c6..92fcb93 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,6 +1,19 @@ #![doc = include_str!("../README.md")] +#![cfg_attr(docsrs, feature(doc_cfg))] +#[cfg_attr(docsrs, doc(cfg(feature = "build")))] #[cfg(feature = "build")] -pub use sabry_build::*; +pub use sabry_build::buildmagic::buildy; +#[cfg_attr(docsrs, doc(cfg(feature = "procmacro")))] #[cfg(feature = "procmacro")] pub use sabry_procmacro::*; + + +// reexports +#[cfg_attr(docsrs, doc(cfg(all(feature = "build", feature = "internals"))))] +#[cfg(all(feature = "build", feature = "internals"))] +pub use sabry_build::*; + +#[cfg_attr(docsrs, doc(cfg(all(feature = "procmacro", feature = "internals"))))] +#[cfg(all(feature = "procmacro", feature = "internals"))] +pub use sabry_intrnl::*;