Add a note about automatic rebuilds to the documentation of

`embed_migrations!`

(Addresses diesel-rs#3119)

Author: weiznich

diesel_migrations/migrations_macros/src/lib.rs

@@ -95,6 +95,24 @@ use proc_macro::TokenStream;
 ///     Ok(())
 /// }
 /// ```
+///
+/// # Automatic rebuilds
+///
+/// Due to limitations in rusts proc-macro API there is currently no
+/// way to signal that a specific proc macro should be rerun if some
+/// external file changes/is added. This implies that `embed_migrations!`
+/// cannot regenerate the list of embedded migrations if **only** the
+/// migrations are changed. This limitation can be solved by adding a
+/// custom `build.rs` file to your crate, such that the crate is rebuild
+/// if the migration directory changes.
+///
+/// Add the following `build.rs` file to your project to fix the problem
+///
+/// ```
+/// fn main() {
+///    println!("cargo:rerun-if-changed=path/to/your/migration/dir/reletive/to/your/Cargo.toml");
+/// }
+/// ```
 #[proc_macro]
 pub fn embed_migrations(input: TokenStream) -> TokenStream {
     embed_migrations::expand(input.to_string())