feat!: expose internals with special feature flag, improve related docs

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"]

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

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"]

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<Item = StyleModule>) -> BuilderResult {
     println!("🧙: This is probably the stderr. Something went wrong:");
 
@@ -49,6 +72,17 @@ pub fn buildy(inline_side_modules: impl IntoIterator<Item = StyleModule>) -> 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 {

sabry_build/src/lib.rs

@@ -2,4 +2,3 @@
 
 pub mod buildmagic;
 pub mod filevisit;
-pub use buildmagic::*;

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"]

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"]

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"]

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::*;