Add "Embedded migrations" guide

[kpcyrd]

I got a very good pointer in https://github.com/diesel-rs/diesel/issues/1840 and would like to add this to the guides list. I think I need to submit my snippet as an example to the diesel repo first, right?

[sgrif]

This doesn't look like it covers anything that isn't already covered by the API documentation for the macro. https://docs.rs/diesel_migrations/1.2.0/diesel_migrations/macro.embed_migrations.html

[kpcyrd]

That's correct, the idea is to have a guide that specifically points to this macro since I assume it's a common question but the solution is a bit hard to discover unless you are already very familiar with diesel. :)

[sgrif]

If the issue is discoverability, that's a separate problem which we should try to address, but I don't think that the correct solution is to just copy/paste the API docs into a guide.

[vmalloc]

I've just hit the same wart with my own code. Googling embed_migrations! (which was itself a hint fetched from another issue discussion) returns an outdated diesel doc from when the macro existed there. From there it's a dead end, which can only be navigated using guesswork.

I think this topic merits at least a link in the guides, or a very short code snippet...

[phiresky]

The macro also doesn't work in the expected way which is not documented anywhere:

use diesel_migrations::embed_migrations;
embed_migrations!();

doesn't work.

while

#[macro_use]
extern crate diesel_migrations;
embed_migrations!();

does

[weiznich]

@phiresky That's currently expected behavior. The last major release of this crate was before the new macro import syntax was support, so we couldn't support it back then.