From 162ee45e050faa73701bb4a02d3cc67b19ebcd5b Mon Sep 17 00:00:00 2001 From: Antonin Peronnet <62420525+rambip@users.noreply.github.com> Date: Wed, 3 Apr 2024 17:53:42 +0200 Subject: [PATCH] Documentation fixes and improvements (#16) * fix out of date macro syntax in docstrings and README * rename assets variables in examples --- README.md | 14 ++++++------- macro/src/lib.rs | 10 +++++----- src/lib.rs | 20 +++++++++---------- .../src/file.rs | 18 ++++++++--------- 4 files changed, 31 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 89b0248..1bf1053 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ The Manganis allows you to submit assets to a build tool that supports collectin If you defined this in a component library: ```rust -const AVIF_ASSET: &str = manganis::file!("./rustacean-flat-gesture.png"); +const AVIF_ASSET: &str = manganis::mg!(file("rustacean-flat-gesture.png")); ``` AVIF_ASSET will be set to a new file name that will be served by some CLI. That file can be collected by any package that depends on the component library. @@ -14,21 +14,21 @@ AVIF_ASSET will be set to a new file name that will be served by some CLI. That const TAILWIND_CLASSES: &str = manganis::classes!("flex flex-col p-5"); // You can also collect arbitrary files. Relative paths are resolved relative to the package root -const _: &str = manganis::mg!(file("./test-package-dependency/src/asset.txt")); +const _: &str = manganis::mg!(file("test-package-dependency/src/asset.txt")); // You can use URLs to copy read the asset at build time const _: &str = manganis::mg!(file("https://rustacean.net/assets/rustacean-flat-happy.png")); // You can collect images which will be automatically optimized -pub const RESIZED_PNG_ASSET: manganis::ImageAsset = - manganis::mg!(image("./rustacean-flat-gesture.png")); +pub const PNG_ASSET: manganis::ImageAsset = + manganis::mg!(image("rustacean-flat-gesture.png")); // Resize the image at compile time to make the assets smaller pub const RESIZED_PNG_ASSET: manganis::ImageAsset = - manganis::mg!(image("./rustacean-flat-gesture.png").size(52, 52)); + manganis::mg!(image("rustacean-flat-gesture.png").size(52, 52)); // Or convert the image at compile time to a web friendly format -pub const AVIF_ASSET: manganis::ImageAsset = manganis::mg!(image("./rustacean-flat-gesture.png") +pub const AVIF_ASSET: manganis::ImageAsset = manganis::mg!(image("rustacean-flat-gesture.png") .format(ImageType::Avif)); // You can even include a low quality preview of the image embedded into the url -pub const AVIF_ASSET: manganis::ImageAsset = manganis::mg!(image("./rustacean-flat-gesture.png") +pub const AVIF_ASSET_LOW: manganis::ImageAsset = manganis::mg!(image("rustacean-flat-gesture.png") .format(ImageType::Avif) .low_quality_preview()); diff --git a/macro/src/lib.rs b/macro/src/lib.rs index 07f7fad..a4ad386 100644 --- a/macro/src/lib.rs +++ b/macro/src/lib.rs @@ -94,7 +94,7 @@ pub fn classes(input: TokenStream) -> TokenStream { /// /// The file builder collects an arbitrary file. Relative paths are resolved relative to the package root /// ```rust -/// const _: &str = manganis::mg!(file("./src/asset.txt")); +/// const _: &str = manganis::mg!(file("src/asset.txt")); /// ``` /// Or you can use URLs to read the asset at build time from a remote location /// ```rust @@ -105,19 +105,19 @@ pub fn classes(input: TokenStream) -> TokenStream { /// /// You can collect images which will be automatically optimized with the image builder: /// ```rust -/// const _: &str = manganis::mg!(image("./rustacean-flat-gesture.png")); +/// const _: manganis::ImageAsset = manganis::mg!(image("rustacean-flat-gesture.png")); /// ``` /// Resize the image at compile time to make the assets file size smaller: /// ```rust -/// const _: &str = manganis::mg!(image("./rustacean-flat-gesture.png").size(52, 52)); +/// const _: manganis::ImageAsset = manganis::mg!(image("rustacean-flat-gesture.png").size(52, 52)); /// ``` /// Or convert the image at compile time to a web friendly format: /// ```rust -/// const _: &str = manganis::mg!(image("./rustacean-flat-gesture.png").format(ImageFormat::Avif).size(52, 52)); +/// const _: manganis::ImageAsset = manganis::mg!(image("rustacean-flat-gesture.png").format(ImageFormat::Avif).size(52, 52)); /// ``` /// You can mark images as preloaded to make them load faster in your app /// ```rust -/// const _: &str = manganis::mg!(image("./rustacean-flat-gesture.png").preload()); +/// const _: manganis::ImageAsset = manganis::mg!(image("rustacean-flat-gesture.png").preload()); /// ``` /// /// # Fonts diff --git a/src/lib.rs b/src/lib.rs index 3a46ab3..d7c5f70 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -97,7 +97,7 @@ impl ImageAssetBuilder { /// The choosing the right format can make your site load much faster. Webp and avif images tend to be a good default for most images /// /// ```rust - /// const _: &str = manganis::mg!(image("https://avatars.githubusercontent.com/u/79236386?s=48&v=4").format(ImageType::Webp)); + /// const _: manganis::ImageAsset = manganis::mg!(image("https://avatars.githubusercontent.com/u/79236386?s=48&v=4").format(ImageType::Webp)); /// ``` #[allow(unused)] pub const fn format(self, format: ImageType) -> Self { @@ -111,7 +111,7 @@ impl ImageAssetBuilder { /// If you only use the image in one place, you can set the size of the image to the size it will be displayed at. This will make the image load faster /// /// ```rust - /// const _: &str = manganis::mg!(image("https://avatars.githubusercontent.com/u/79236386?s=48&v=4").size(512, 512)); + /// const _: manganis::ImageAsset = manganis::mg!(image("https://avatars.githubusercontent.com/u/79236386?s=48&v=4").size(512, 512)); /// ``` #[allow(unused)] pub const fn size(self, x: u32, y: u32) -> Self { @@ -125,7 +125,7 @@ impl ImageAssetBuilder { /// A low quality preview is a small version of the image that will load faster. This is useful for large images on mobile devices that may take longer to load /// /// ```rust - /// const _: &str = manganis::mg!(image("https://avatars.githubusercontent.com/u/79236386?s=48&v=4").low_quality_preview()); + /// const _: manganis::ImageAsset = manganis::mg!(image("https://avatars.githubusercontent.com/u/79236386?s=48&v=4").low_quality_preview()); /// ``` #[allow(unused)] pub const fn low_quality_preview(self) -> Self { @@ -139,7 +139,7 @@ impl ImageAssetBuilder { /// Preloading an image will make the image start to load as soon as possible. This is useful for images that will be displayed soon after the page loads or images that may not be visible immediately, but should start loading sooner /// /// ```rust - /// const _: &str = manganis::mg!(image("https://avatars.githubusercontent.com/u/79236386?s=48&v=4").preload()); + /// const _: manganis::ImageAsset = manganis::mg!(image("https://avatars.githubusercontent.com/u/79236386?s=48&v=4").preload()); /// ``` #[allow(unused)] pub const fn preload(self) -> Self { @@ -153,7 +153,7 @@ impl ImageAssetBuilder { /// URL encoding an image inlines the data of the image into the URL. This is useful for small images that should load as soon as the html is parsed /// /// ```rust - /// const _: &str = manganis::mg!(image("https://avatars.githubusercontent.com/u/79236386?s=48&v=4").url_encoded()); + /// const _: manganis::ImageAsset = manganis::mg!(image("https://avatars.githubusercontent.com/u/79236386?s=48&v=4").url_encoded()); /// ``` #[allow(unused)] pub const fn url_encoded(self) -> Self { @@ -167,19 +167,19 @@ impl ImageAssetBuilder { /// /// You can collect images which will be automatically optimized with the image builder: /// ```rust -/// const _: &str = manganis::mg!(image("./rustacean-flat-gesture.png")); +/// const _: manganis::ImageAsset = manganis::mg!(image("rustacean-flat-gesture.png")); /// ``` /// Resize the image at compile time to make the assets file size smaller: /// ```rust -/// const _: &str = manganis::mg!(image("./rustacean-flat-gesture.png").size(52, 52)); +/// const _: manganis::ImageAsset = manganis::mg!(image("rustacean-flat-gesture.png").size(52, 52)); /// ``` /// Or convert the image at compile time to a web friendly format: /// ```rust -/// const _: &str = manganis::mg!(image("./rustacean-flat-gesture.png").format(ImageFormat::Avif).size(52, 52)); +/// const _: manganis::ImageAsset = manganis::mg!(image("rustacean-flat-gesture.png").format(ImageType::Avif).size(52, 52)); /// ``` /// You can mark images as preloaded to make them load faster in your app /// ```rust -/// const _: &str = manganis::mg!(image("./rustacean-flat-gesture.png").preload()); +/// const _: manganis::ImageAsset = manganis::mg!(image("rustacean-flat-gesture.png").preload()); /// ``` #[allow(unused)] pub const fn image(path: &'static str) -> ImageAssetBuilder { @@ -268,7 +268,7 @@ pub const fn font() -> FontAssetBuilder { /// /// The file builder collects an arbitrary file. Relative paths are resolved relative to the package root /// ```rust -/// const _: &str = manganis::mg!(file("./src/asset.txt")); +/// const _: &str = manganis::mg!(file("src/asset.txt")); /// ``` /// Or you can use URLs to read the asset at build time from a remote location /// ```rust diff --git a/test-package/test-package-nested-dependency/src/file.rs b/test-package/test-package-nested-dependency/src/file.rs index a9b2e24..a0335a9 100644 --- a/test-package/test-package-nested-dependency/src/file.rs +++ b/test-package/test-package-nested-dependency/src/file.rs @@ -1,23 +1,23 @@ const _: &str = manganis::classes!("flex flex-row p-5"); -pub const CSS_ASSET: &str = manganis::mg!(file("./style.css")); -pub const PNG_ASSET: &str = manganis::mg!(file("./rustacean-flat-gesture.png")); +pub const CSS_ASSET: &str = manganis::mg!(file("style.css")); +pub const PNG_ASSET: &str = manganis::mg!(file("rustacean-flat-gesture.png")); pub const RESIZED_PNG_ASSET: manganis::ImageAsset = - manganis::mg!(image("./rustacean-flat-gesture.png").size(52, 52)); + manganis::mg!(image("rustacean-flat-gesture.png").size(52, 52)); pub const JPEG_ASSET: manganis::ImageAsset = - manganis::mg!(image("./rustacean-flat-gesture.png").format(ImageType::Jpg)); + manganis::mg!(image("rustacean-flat-gesture.png").format(ImageType::Jpg)); pub const RESIZED_JPEG_ASSET: manganis::ImageAsset = - manganis::mg!(image("./rustacean-flat-gesture.png") + manganis::mg!(image("rustacean-flat-gesture.png") .format(ImageType::Jpg) .size(52, 52)); pub const AVIF_ASSET: manganis::ImageAsset = - manganis::mg!(image("./rustacean-flat-gesture.png").format(ImageType::Avif)); + manganis::mg!(image("rustacean-flat-gesture.png").format(ImageType::Avif)); pub const RESIZED_AVIF_ASSET: manganis::ImageAsset = - manganis::mg!(image("./rustacean-flat-gesture.png") + manganis::mg!(image("rustacean-flat-gesture.png") .format(ImageType::Avif) .size(52, 52)); pub const WEBP_ASSET: manganis::ImageAsset = - manganis::mg!(image("./rustacean-flat-gesture.png").format(ImageType::Webp)); + manganis::mg!(image("rustacean-flat-gesture.png").format(ImageType::Webp)); pub const RESIZED_WEBP_ASSET: manganis::ImageAsset = - manganis::mg!(image("./rustacean-flat-gesture.png") + manganis::mg!(image("rustacean-flat-gesture.png") .format(ImageType::Webp) .size(52, 52));