Some Docs for stylance main crate.

stylance/src/lib.rs

@@ -1,6 +1,98 @@
+//! # About stylance
+//!
+//! Stylance is a scoped CSS library for rust.
+//!
+//! Use it in conjunction with [stylance-cli](https://crates.io/crates/stylance-cli).
+//!
+//! # Feature flags
+//!
+//! - `nightly`: Enables importing styles with paths relative to the rust file where the macro was called.
+//!
+//! # Usage
+//!
+//! Create a .module.css file inside your rust source directory
+//! ```scss
+//! // src/component1/style.module.css
+//!
+//! .header {
+//!     color: red;
+//! }
+//!
+//! .contents {
+//!     border: 1px solid black;
+//! }
+//! ```
+//!
+//! Then import that file from your rust code:
+//! ```rust
+//! stylance::import_crate_style!(style, "src/component1/style.module.css");
+//!
+//! fn use_style() {
+//!     println!("{}", style::header);
+//! }
+//! ```
+//!
+//! ### Accessing non-scoped global class names with `:global(.class)`
+//!
+//! Sometimes you may want to use an external classname in your .module.css file.
+//!
+//! For this you can wrap the global class name with `:global()`, this instructs stylance to leave that class name alone.
+//!
+//! ```css
+//! .contents :global(.paragraph) {
+//!     color: blue;
+//! }
+//! ```
+//!
+//! This will expand to
+//! ```css
+//! .contents-539306b .paragraph {
+//!     color: blue;
+//! }
+//! ```
+//!
+//! # Transforming and bundling your .module.css files
+//!
+//! To transform your .module.css and .module.scss into a bundled css file use [stylance-cli](https://crates.io/crates/stylance-cli).
+//!
+//!
+
+#![feature(doc_cfg)]
+
+#[doc(hidden)]
 pub use stylance_macros::*;
 
-#[cfg(feature = "nightly")]
+/// Reads a css file at compile time and generates a module containing the classnames found inside that css file.
+/// Path is relative to the file that called the macro.
+///
+/// ### Syntax
+/// ```rust
+/// import_style!([pub] module_identifier, style_path);
+/// ```
+/// - Optionally add pub keyword before `module_identifier` to make the generated module public.
+/// - `module_identifier`: This will be used as the name of the module generated by this macro.
+/// - `style_path`: This should be a string literal with the path to a css file inside your rust
+/// crate. The path is relative to the file where this macro was called from.
+///
+/// ### Example
+/// ```rust
+/// // style.css is located in the same directory as this rust file.
+/// stylance::import_style!(pub style, "style.css");
+///
+/// fn use_style() {
+///     println!("{}", style::header);
+/// }
+/// ```
+///
+/// ### Expands into
+///
+/// ```rust
+/// pub mod style {
+///     pub const header: &str = "header-539306b";
+///     pub const contents: &str = "contents-539306b";
+/// }
+/// ```
+#[doc(cfg(feature = "nightly"))]
 #[macro_export]
 macro_rules! import_style {
     ($ident:ident, $str:expr) => {
@@ -15,6 +107,34 @@ macro_rules! import_style {
     };
 }
 
+/// Reads a css file at compile time and generates a module containing the classnames found inside that css file.
+///
+/// ### Syntax
+/// ```rust
+/// import_crate_style!([pub] module_identifier, style_path);
+/// ```
+/// - Optionally add pub keyword before `module_identifier` to make the generated module public.
+/// - `module_identifier`: This will be used as the name of the module generated by this macro.
+/// - `style_path`: This should be a string literal with the path to a css file inside your rust
+/// crate. The path must be relative to the cargo manifest directory (The directory that has Cargo.toml).
+///
+/// ### Example
+/// ```rust
+/// stylance::import_crate_style!(pub style, "path/from/manifest_dir/to/style.css");
+///
+/// fn use_style() {
+///     println!("{}", style::header);
+/// }
+/// ```
+///
+/// ### Expands into
+///
+/// ```rust
+/// pub mod style {
+///     pub const header: &str = "header-539306b";
+///     pub const contents: &str = "contents-539306b";
+/// }
+/// ```
 #[macro_export]
 macro_rules! import_crate_style {
     ($ident:ident, $str:expr) => {