[Docs] Add .dstack/profiles.yml to Reference and Protips (#3093)

Author: peterschmidt85

docs/assets/stylesheets/extra.css

@@ -804,7 +804,7 @@ body {
         display: inline-block;
         font-size: 17px;
         font-weight: 600;
-        line-height: 1.4rem;
+        /* line-height: 1.4rem; */
         /*letter-spacing: -0.5px;*/
         position: relative;
         left: -11px;
@@ -866,7 +866,7 @@ body {
 }
 
 .md-sidebar--primary .md-nav__link, .md-sidebar--post .md-nav__link {
-    padding: 5px 15px 4px;
+    padding: 4px 15px 4px;
     margin-top: 0;
 }
 
@@ -989,6 +989,10 @@ html .md-footer-meta.md-typeset a:is(:focus,:hover) {
     .md-nav--integrated>.md-nav__list>.md-nav__item--active .md-nav--secondary {
         margin-bottom: 0;
     }
+
+    .md-nav--primary .md-nav__list {
+        padding-bottom: .2rem;
+    }
 }
 
 .md-typeset :where(ol, ul) {

docs/docs/guides/protips.md

@@ -321,6 +321,33 @@ retry:
 
 </div>
 
+## Profiles
+
+Sometimes, you may want to reuse parameters across runs or set defaults so you don’t have to repeat them in every configuration. You can do this by defining a profile.
+
+??? info ".dstack/profiles.yml"
+    A profile file can be created either globally in `~/.dstack/profiles.yml` or locally in `.dstack/profiles.yml`:
+
+    ```yaml
+    profiles:
+      - name: my-profile
+        # If set to true, this profile will be applied automatically
+        default: true
+
+        # The spot pololicy can be "spot", "on-demand", or "auto"
+        spot_policy: auto
+        # Limit the maximum price of the instance per hour
+        max_price: 1.5
+        # Stop any run if it runs longer that this duration
+        max_duration: 1d
+        # Use only these backends
+        backends: [azure, lambda]
+    ```
+
+    Check [`.dstack/profiles.yml`](../reference/profiles.yml.md) to see what properties can be defined there.
+    
+A profile can be set as `default` to apply automatically to any run, or specified with `--profile NAME` in `dstack apply`.
+
 ## Projects
 
 If you're using multiple `dstack` projects (e.g., from different `dstack` servers),  

docs/docs/reference/profiles.yml.md

@@ -1,42 +1,32 @@
-# profiles.yml
+# .dstack/profiles.yml
 
-Sometimes, you may want to reuse the same parameters across different [`.dstack.yml`](dstack.yml.md) configurations.
+Sometimes, you may want to reuse the same parameters across runs or set your own defaults so you don’t have to repeat them in every run configuration. You can do this by defining a profile, either globally in `~/.dstack/profiles.yml` or locally in `.dstack/profiles.yml`. 
 
-This can be achieved by defining those parameters in a profile.
+A profile can be set as `default` to apply automatically to any run, or specified with `--profile NAME` in `dstack apply`.
 
-Profiles can be defined on the repository level (via the `.dstack/profiles.yml` file in the root directory of the
-repository) or on the global level (via the `~/.dstack/profiles.yml` file).
-
-Any profile can be marked as default so that it will be applied automatically for any run. Otherwise, you can refer to a specific profile
-via `--profile NAME` in `dstack apply`.
-
-### Example
+Example:
 
 <div editor-title=".dstack/profiles.yml"> 
 
 ```yaml
 profiles:
   - name: my-profile
+    # If set to true, this profile will be applied automatically
+    default: true
 
     # The spot pololicy can be "spot", "on-demand", or "auto"
     spot_policy: auto
-
     # Limit the maximum price of the instance per hour
     max_price: 1.5
-
     # Stop any run if it runs longer that this duration
     max_duration: 1d
-
     # Use only these backends
     backends: [azure, lambda]
-
-    # If set to true, this profile will be applied automatically
-    default: true
 ```
 
 </div>
 
-The profile configuration supports many properties. See below.
+The profile configuration supports most properties that a run configuration supports — see below.
 
 ### Root reference
 
@@ -51,3 +41,9 @@ The profile configuration supports many properties. See below.
 #SCHEMA# dstack._internal.core.models.profiles.ProfileRetry
     overrides:
       show_root_heading: false
+
+### `utilization_policy`
+
+#SCHEMA# dstack._internal.core.models.profiles.UtilizationPolicy
+    overrides:
+      show_root_heading: false