Updated getting started

Author: gammelalf

docs/rorm/getting_started.md

@@ -1,4 +1,12 @@
-## Add `rorm` to your dependencies 
+## Dependencies
+
+### `tokio`
+
+Rorm uses `async` rust and the only supported runtime is `tokio`.
+
+If you never heard of it, you probably should look up some quick introduction to `async`.
+
+### `rorm`
 
 ```toml
 [dependencies]
@@ -22,62 +30,7 @@ rorm = { git = "https://github.com/rorm-orm/rorm", branch = "dev" }
     To use the dev branch you want to use the docs generated by
     executing `cargo doc`.
 
-### Choose your async runtime
-
-Currently, there are two runtimes supported.
-Choose one of them and enable the respective crate feature to make `rorm` work:
-
-- `tokio`
-- `async-std`
-
-Add the chosen runtime to the features of `rorm`, for example:
-
-```toml
-[dependencies]
-rorm = { version = "*", features = ["tokio"] }
-```
-
-### Setup `rorm-main`
-
-This step is strictly speaking optional, but it's highly recommended.
-`rorm-main` is a feature to ease the integration with the migrator,
-therefore it's unnecessary if the migrator isn't used. It overwrites the
-`main` function when activated, which will produce a JSON file of the
-currently known models in the source code. The recommended procedure is to
-use this feature in a build pipeline, for extended testing purposes or
-whenever you want to make new migrations of the models.
-
-1. Add the `rorm-main` feature in your `Cargo.toml`:
-   ```toml
-   [features]
-   rorm-main = []
-   ```
-   Make sure to disable this feature by default. For example,
-   IntelliJ manages which features will be enabled
-   internally. When looking at the `[features]` section,
-   it will show them using checkboxes at the left edge.
-   `rorm-main` should not be set.
-
-2. Annotate your main function:
-   ```rust
-   #[rorm::rorm_main]
-   fn main() {
-       // ...
-   }
-   ```
-   This attribute won't do anything unless the `rorm-main` feature
-   becomes enabled. Depending on the chosen runtime implementation,
-   you may need another annotation for that. For example, for Tokio
-   you would combine the annotations in one piece as follows:
-   ```rust
-   #[rorm::rorm_main]
-   #[tokio::main]
-   async fn main() {
-       // ...
-   }
-   ```
-
-### Project setup
+### CLI tool
 
 Make sure to have the CLI utility `rorm-cli` available:
 
@@ -88,6 +41,9 @@ cargo install -f rorm-cli
 Head over to [project setup](project_setup.md) for more details,
 especially if you want to take some additional configuration for your setup.
 
+Alternatively you can enable `rorm`'s `cli` feature which re-exports the binaries functions.
+This allows you to integrate the `migrate` command into your binary's cli.
+
 ## Define a model
 
 ```rust
@@ -136,27 +92,23 @@ pub(crate) struct UserNew {
 ### Generate migrator files
 
 After the first database model has been added, the current models
-can be extracted from the Rust source code:
+can be extracted from the Rust source code.
 
-```bash
-cargo run --features rorm-main
+```rust
+rorm::write_models(File::create(".models.json")?)?
 ```
 
 This will create a file `.models.json` to be processed by the migrator. So,
 you need to run this every time you want to generate new migrations.
-You might want to add it to a build chain if you're using any.
-It requires the `rorm-main` feature to be set up properly
-(see [above](#setup-rorm-main)).
+
+You could run this snippet through some kind of subcommand in your binary's development builds.
 
 ### Make migration TOML files from the migrator JSON file
 
 ```sh
 rorm-cli make-migrations
 ```
 
-Otherwise, if you configured the commands as outlined [here](project_setup.md),
-it's also possible to invoke those `rorm-cli` commands via `cargo make <cmd>`.
-
 This command will read the previously generated JSON file `.models.json`
 to compute the required database migrations as TOML files in the
 directory `migrations/`. Note that those TOML files need to be applied

docs/rorm/project_setup.md

@@ -1,5 +1,10 @@
 # Project setup
 
+!!! warning
+
+    This page is outdated and does not reflect the current
+    recommendations of the rorm authors.
+
 Install the necessary CLI tools:
 ```bash
 cargo install -f cargo-make rorm-cli