Change the structure of README (#46)

* Change the structure of README

* Restore removed example, consisted new lines

* Expand Basic usage section

* Apply suggestions from code review

Co-authored-by: Predrag Gruevski <2348618+obi1kenobi@users.noreply.github.com>

---------

Co-authored-by: Predrag Gruevski <2348618+obi1kenobi@users.noreply.github.com>

README.md

@@ -8,12 +8,32 @@ Lint your crate API changes for semver violations.
   run: # your `cargo publish` code here
 ```
 
+* [Basic usage](#basic-usage)
 * [Input options](#input-options)
 * [Example scenarios](#example-scenarios)
-  * [Use in workspaces with a single crate](#use-in-workspaces-with-a-single-crate)
-  * [Use in workspaces with more than one crate](#use-in-workspaces-with-more-than-one-crate)
+  * [Use outside root directory of a crate or a workspace](#use-outside-root-directory-of-a-crate-or-a-workspace)
+  * [Specify crates to be checked](#specify-crates-to-be-checked)
+  * [Exclude crates from being checked](#exclude-crates-from-being-checked)
+  * [Use toolchain other than `stable`](#use-toolchain-other-than-stable)
 * [Customizing baseline rustdoc caching strategy](#customizing-baseline-rustdoc-caching-strategy)
 
+## Basic usage
+
+The action is designed to be used right before `cargo publish`. It will check the API of your crate for semver violations, comparing it to the latest normal (not pre-release or yanked) version published on crates.io. At the moment, the action does not support checking against other baselines, such as the destination branch of a pull request.
+
+If your repository is just a crate or a workspace, the action will work out-of-the-box with sensible defaults:
+```yaml
+semver-checks:
+  runs-on: ubuntu-latest
+  steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+    - name: Check semver
+      uses: obi1kenobi/cargo-semver-checks-action@v2
+```
+> **Note**
+> By default, the action always installs the latest stable Rust and ignores the `rust-toolchain.toml` file and any local overrides. This ensures we use the latest version of rustdoc, taking advantage of the latest bugfixes and avoiding false-positives. If you want to change this default behavior, see [Use toolchain other than `stable`](#use-toolchain-other-than-stable).
+
 ## Input options
 
 Every argument is optional.
@@ -32,9 +52,9 @@ Every argument is optional.
 
 ## Example scenarios
 
-### Use in workspaces with a single crate
+### Use outside root directory of a crate or a workspace
 
-The action will work out-of-the-box if it is run inside the package root directory. When the package location is different, you have to specify the path to its `Cargo.toml` file:
+The action will work well with defaults settings if it is run inside the package root directory. When the package location is different, you have to specify the path to its `Cargo.toml` file:
 ```yaml
 - name: Check semver for my-crate
   uses: obi1kenobi/cargo-semver-checks-action@v2
@@ -42,9 +62,17 @@ The action will work out-of-the-box if it is run inside the package root directo
     manifest-path: semver/my-crate/Cargo.toml  # or just semver/my-crate/
 ```
 
-### Use in workspaces with more than one crate
+In the same way you can provide the path to the workspace `Cargo.toml` file, which will result in checking all its crates:
+```yaml
+- name: Check semver for all crates from my-workspace
+  uses: obi1kenobi/cargo-semver-checks-action@v2
+  with:
+    manifest-path: semver/my-workspace/Cargo.toml  # or just semver/my-workspace/
+```
 
-By default, if workspace contains multiple crates, all of them are checked for semver violations. You can specify one or more crates to be checked instead using `package`, `exclude` or `manifest-path`.
+### Specify crates to be checked
+
+By default, all packages defined in the `Cargo.toml` file are processed. You can specify one or more packages to be checked instead using input `package`.
 
 For example, this will check `my-crate-api` and `my-crate-core`:
 ```yaml
@@ -53,7 +81,19 @@ For example, this will check `my-crate-api` and `my-crate-core`:
   with:
     package: my-crate-api, my-crate-core
 ```
-And this will process all crates from the current workspace except `my-crate-tests`:
+
+Inputs `package` and `manifest-path` might be used together:
+```yaml
+- name: Check semver for my-crate from my-workspace
+  uses: obi1kenobi/cargo-semver-checks-action@v2
+  with:
+    manifest-path: semver/my-workspace/Cargo.toml  # or just semver/my-workspace/
+    package: my-crate
+```
+
+### Exclude crates from being checked
+
+This will process all crates from the current workspace except `my-crate-tests`:
 ```yaml
 - name: Check semver for all crates except my-crate-tests
   uses: obi1kenobi/cargo-semver-checks-action@v2
@@ -61,21 +101,25 @@ And this will process all crates from the current workspace except `my-crate-tes
     exclude: my-crate-tests
 ```
 
-If the action is not run inside the workspace root directory, you again have to specify the path to its `Cargo.toml` file:
-```yaml
-- name: Check semver for all crates from my-workspace
-  uses: obi1kenobi/cargo-semver-checks-action@v2
-  with:
-    manifest-path: semver/my-workspace/Cargo.toml  # or just semver/my-workspace/
-```
+### Use toolchain other than `stable`
 
-The two above might be also used together:
+By default, the actions installs (if necessary) and then uses the `stable` toolchain regardless of local overrides and the `rust-toolchain.toml` file. You can force using a different toolchain using `rust-toolchain`:
 ```yaml
-- name: Check semver for my-crate from my-workspace
+- name: Check semver
   uses: obi1kenobi/cargo-semver-checks-action@v2
   with:
-    manifest-path: semver/my-workspace/Cargo.toml  # or just semver/my-workspace/
-    package: my-crate
+    rust-toolchain: nightly
+```
+If you want to setup the toolchain manually, you can set `rust-toolchain` to `manual`. In this case, the action assumes some Rust toolchain is already installed and uses the default one:
+```yaml
+- name: Setup Rust
+  uses: dtolnay/rust-toolchain@master
+  with:
+    toolchain: stable 2 months ago
+- name: Check semver
+  uses: obi1kenobi/cargo-semver-checks-action@v2
+  with:
+    rust-toolchain: manual
 ```
 
 ## Customizing baseline rustdoc caching strategy