Restore manganis optimizations (#3195)

* Create a crate for constant serialization of config structs for manganis
* use SerializeConst for the image asset builder
* switch to a declarative macro for assets
* add serializable options for each asset type
* implement the new manganis macro
* optimize assets in the CLI
* Fix assets with dioxus formattable
* reduce fuzzing test limits
* use the new syntax in examples
* fix avif support
* Fix manganis doc tests
* cache asset optimization
* Split out asset and bundled asset
* make hash pointer width independent
* Fix manganis macro docs
* add constvec::is_empty method to fix clippy lint
* remove nasm feature
* simplify test_rsplit_once test so typos passes
* revert example change from clippy fix
* always accept unix paths
* fix windows path seperator
* fix folder asset hash
* Optimize assets in a blocking task
* Fix asset options docs
* Document Asset and BundledAsset
* simplify the linker macro a bit
* add more docs to AssetParser expansion
* add image format helpers
* Split by  both unix and windows path separators and take the smallest one

packages/manganis/manganis-macro/src/lib.rs

@@ -11,6 +11,42 @@ pub(crate) mod linker;
 use linker::generate_link_section;
 
 /// The asset macro collects assets that will be included in the final binary
+///
+/// # Files
+///
+/// The file builder collects an arbitrary file. Relative paths are resolved relative to the package root
+/// ```rust
+/// # use manganis::{asset, Asset};
+/// const _: Asset = asset!("/assets/asset.txt");
+/// ```
+/// Or you can use URLs to read the asset at build time from a remote location
+/// ```rust
+/// # use manganis::{asset, Asset};
+/// const _: Asset = asset!("/assets/image.png");
+/// ```
+///
+/// # Images
+///
+/// You can collect images which will be automatically optimized with the image builder:
+/// ```rust
+/// # use manganis::{asset, Asset};
+/// const _: Asset = asset!("/assets/image.png");
+/// ```
+/// Resize the image at compile time to make the assets file size smaller:
+/// ```rust
+/// # use manganis::{asset, Asset, ImageAssetOptions, ImageSize};
+/// const _: Asset = asset!("/assets/image.png", ImageAssetOptions::new().with_size(ImageSize::Manual { width: 52, height: 52 }));
+/// ```
+/// Or convert the image at compile time to a web friendly format:
+/// ```rust
+/// # use manganis::{asset, Asset, ImageAssetOptions, ImageSize, ImageFormat};
+/// const _: Asset = asset!("/assets/image.png", ImageAssetOptions::new().with_format(ImageFormat::Avif));
+/// ```
+/// You can mark images as preloaded to make them load faster in your app
+/// ```rust
+/// # use manganis::{asset, Asset, ImageAssetOptions};
+/// const _: Asset = asset!("/assets/image.png", ImageAssetOptions::new().with_preload(true));
+/// ```
 #[proc_macro]
 pub fn asset(input: TokenStream) -> TokenStream {
     let asset = parse_macro_input!(input as asset::AssetParser);