Better Document how diesel_cli searches for migrations and how it works with cargo workspaces

[hasezoey]

Better document how diesel_cli searches and created migrations and how it interacts with Cargo workspaces

Basically i could not find any documentation of how diesel_cli actually searches for a Cargo.toml and how consistent it is and also how it interacts with Cargo Workspaces

For Example:

• how does diesel_cli handle being in the cargo workspace root (like /)
• how does diesel_cli handle being in a sub-directory of a workspace / normal-project (like /target)
• how does diesel_cli handle being in a workspace crate (like /crates/library)

also, diesel_migrations::embed_migrations should link to where diesel_cli describes how it searches

My use-case:
i have a mono-repo project which uses cargo-workspaces, where the structure is:

• /Cargo.toml - defining the workspace
• /crates/bin/Cargo.toml - defining a binary crate
• /crates/lib/Cargo.toml - defining a library crate
• /crates/lib/migrations/ - all migrations are in the lib crate (created with diesel setup while CWD was /crates/lib)

and i would like to include the migrations in the library crate with diesel_migrations::embed_migrations, but i am unsure of what path i need to input:

• do i need to input relative to the lib crate's Cargo.toml, or
• do i need to input relative to the workspace's root Cargo.toml, or
• do i need to input relative to the current file

Note: from my testing, in this case my answer is "i need to input relative to the lib crate's Cargo.toml" (which it seems to auto-detect)

[weiznich]

Improvements to our documentation is always welcome, as we unfortunately do not have the capacity to document all stuff in detail. PR's that improve the documentation are always welcome.

For the cli there is some inline documentation in the code:

diesel/diesel_cli/src/main.rs

Lines 253 to 262 in c794c3e

	/// Checks for a migrations folder in the following order :
	/// 1. From the CLI arguments
	/// 2. From the MIGRATION_DIRECTORY environment variable
	/// 3. From `diesel.toml` in the `migrations_directory` section
	///
	/// Else try to find the migrations directory with the
	/// `find_migrations_directory` in the diesel_migrations crate.
	///
	/// Returns a `MigrationError::MigrationDirectoryNotFound` if
	/// no path to the migration directory is found.

I'm honestly not sure what would be the right place to document something like that.
For the embed_migration! macro the master branch documentation already contains some details.