- Massive overhaul of the docs and learning materials

dstackai · Dec 20, 2023 · 97bc27f · 97bc27f
1 parent 809e0ed
commit 97bc27f
Show file tree

Hide file tree

Showing 30 changed files with 550 additions and 373 deletions.
diff --git a/docs/assets/stylesheets/extra.css b/docs/assets/stylesheets/extra.css
@@ -620,6 +620,10 @@ body {
         display: flex;
     }
 
+    .md-sidebar__inner > .md-nav--primary > .md-nav__list > .md-nav__item > .md-nav > .md-nav__list > .md-nav__item:not(.md-nav__item--section) {
+        display: none;
+    }
+
     .md-nav__item--section > .md-nav__link {
         text-transform: uppercase;
         display: inline-block;
@@ -710,7 +714,7 @@ body {
 
 .md-path__link {
     color: var(--md-default-fg-color);
-    ont-size: 0.7rem;
+    font-size: 0.7rem;
 }
 
 @media screen and (min-width: 76.1875em) {
@@ -1354,9 +1358,9 @@ div[editor-title] code .editor-title {
     white-space: nowrap;
 }
 
-.md-blog-sidebar .md-nav__link--active {
+/*.md-blog-sidebar .md-nav__link--active {
     display: none;
-}
+}*/
 
 [data-ty].no-newline, .no-newline {
     display: inline-block;

diff --git a/docs/assets/stylesheets/landing.css b/docs/assets/stylesheets/landing.css
@@ -216,7 +216,7 @@
 
 .md-header__buttons .md-button--primary,
 .md-header__buttons .md-button-secondary {
-    font-weight: 500 !important;
+    font-weight: 400 !important;
     white-space: nowrap;
 }
 
@@ -250,13 +250,27 @@
 }
 
 .tx-landing__highlights_text h2 {
-    font-size: 2.2em;
+    font-size: 2.0em;
     max-width: 500px;
     margin-top: 1.75em;
     margin-bottom: 2.5em;
     letter-spacing: -1.5px;
 }
 
+.tx-landing__highlights_cta {
+    margin-top: 3vw;
+}
+
+.tx-landing__highlights_cta a {
+    display: inline-block;
+    font-size: 19px;
+    margin-top: 30px;
+    border: 1px solid;
+    padding: 10px 20px;
+    border-radius: 30px;
+    font-weight: 500;
+}
+
 .tx-landing__highlights_text h2 .gradient {
     background: -webkit-linear-gradient(45deg, #0048ff, #ce00ff);
     -webkit-background-clip: text;
@@ -690,3 +704,10 @@
         font-size: 2.5rem;
     }
 }
+
+.typed-cursor {
+    background: linear-gradient(90deg, #4631C8 -1.29%, #CD4AE2 88.05%, #FFD43C 111.26%);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    padding: 0 7px;
+}
diff --git a/docs/blog/posts/simplified-cloud-setup.md b/docs/blog/posts/simplified-cloud-setup.md
@@ -80,7 +80,7 @@ run = client.runs.submit(
 
 The `dstack.api.Run` instance provides methods for various operations including attaching to the run, 
 forwarding ports to `localhost`, retrieving status, stopping, and accessing logs. For more details, refer to 
-the [example](../../examples/deploy-python.md) and [reference](../../docs/reference/api/python/index.md).
+the [example](../../learn/deploy-python.md) and [reference](../../docs/reference/api/python/index.md).
 
 ## Other changes
 
@@ -101,7 +101,7 @@ This means you'll need to delete `~/.dstack` and configure `dstack` from scratch
 3. Configure clouds via `~/.dstack/server/config.yml` (see the [new guide](../../docs/config/server.md))
 4. Run `dstack server`
 
-The [documentation](../../docs/index.md) and [examples](../../examples/index.md) are updated.
+The [documentation](../../docs/index.md) and [examples](../../learn/index.md) are updated.
 
 ## Give it a try
 

diff --git a/docs/docs/config/server.md b/docs/docs/config/server.md
@@ -406,3 +406,11 @@ projects:
 </div>
 
 If regions aren't specified, `dstack` will use all available regions.
+
+## What's next?
+
+1. Read about [dev environments](../guides/dev-environments.md), [tasks](../guides/tasks.md), 
+    and [services](../guides/services.md)
+2. See all [learning materials](../../learn/index.md)
+3. Join the [Discord server](https://discord.gg/u8SmfwPpMd)
+4. Sign up for [dstack Cloud](../../index.md) (if you'd like the server to be hosted by `dstack`)
diff --git a/docs/docs/guides/dev-environments.md b/docs/docs/guides/dev-environments.md
@@ -26,7 +26,7 @@ ide: vscode
 !!! info "Configuration options"
     You can specify your own Docker image, configure environment variables, etc.
     If no image is specified, `dstack` uses its own Docker image (pre-configured with Python, Conda, and essential CUDA drivers).
-    For more details, refer to the [Reference](../reference/dstack.yml/dev-environment.md).
+    For more details, refer to the [Reference](../reference/dstack.yml.md#dev-environment).
 
 ## Run the configuration
 
@@ -73,4 +73,9 @@ automatically.
 ??? info ".gitignore"
     When running a dev environment, `dstack` uses the exact version of code from your project directory. 
 
-    If there are large files, consider creating a `.gitignore` file to exclude them for better performance.
+    If there are large files, consider creating a `.gitignore` file to exclude them for better performance.
+
+## What's next?
+
+1. See all [learning materials](../../learn/index.md)
+2. Check the [reference](../reference/dstack.yml.md#dev-environment)
diff --git a/docs/docs/guides/services.md b/docs/docs/guides/services.md
@@ -67,7 +67,7 @@ which are pre-configured with Python, Conda, and essential CUDA drivers.
 !!! info "Configuration options"
     Configuration file allows you to specify a custom Docker image, environment variables, and many other 
     options.
-    For more details, refer to the [Reference](../reference/dstack.yml/service.md).
+    For more details, refer to the [Reference](../reference/dstack.yml.md#service).
 
 ### Run the configuration
 
@@ -102,4 +102,12 @@ Once the service is deployed, its endpoint will be available at
     and many other options (incl. spot instances, disk size, max price, max duration, retry policy, etc.).
     For more details, refer to the [Reference](../reference/cli/index.md#dstack-run).
 
-[//]: # (TODO: Example)
+[//]: # (TODO: Example)
+
+What's next?
+
+1. Check the [Text Generation Inference](../../learn/tgi.md) and [vLLM](../../learn/vllm.md) examples
+2. Read about [dev environments](../guides/dev-environments.md) 
+    and [tasks](../guides/tasks.md)
+3. See all [learning materials](../../learn/index.md)
+4. Check the [reference](../reference/dstack.yml.md#service)
diff --git a/docs/docs/guides/tasks.md b/docs/docs/guides/tasks.md
@@ -54,7 +54,7 @@ which are pre-configured with Python, Conda, and essential CUDA drivers.
 !!! info "Configuration options"
     Configuration file allows you to specify a custom Docker image, ports, environment variables, and many other 
     options.
-    For more details, refer to the [Reference](../reference/dstack.yml/task.md).
+    For more details, refer to the [Reference](../reference/dstack.yml.md#task).
 
 ### Run the configuration
 
@@ -153,4 +153,12 @@ $ dstack run . -f train.dstack.yml --retry-limit 3h
 
 For more details on the `dstack run` command, refer to the [Reference](../reference/cli/index.md#dstack-run).
 
-[//]: # (Using the API)
+[//]: # (Using the API)
+
+## What's next?
+
+1. Check the [QLoRA](../../learn/qlora.md) example
+2. Read about [dev environments](../guides/dev-environments.md) 
+    and [services](../guides/services.md)
+3. See all [learning materials](../../learn/index.md)
+4. Check the [reference](../reference/dstack.yml.md#task)
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -95,8 +95,8 @@ Once `dstack` is set up, you can use CLI or API.
 
 ## Using the CLI
 
-The CLI allows you to define configurations (what you want to run) as YAML files and run them using the `dstack run`
-command.
+With `dstack`, you can define what you want to run as YAML [configuration files](reference/dstack.yml.md) 
+and run them using the `dstack run` command.
 
 ### Define a configuration
 
@@ -182,4 +182,12 @@ Epoch 2:  100% 1719/1719 [00:18<00:00, 92.32it/s, loss=0.0981, acc=0.969]
 </div>
 
 No need to worry about copying code, setting up environment, IDE, etc. `dstack` handles it all 
-automatically.
+automatically.
+
+## What's next?
+
+1. Configure [cloud accounts](config/server.md)
+2. Read about [dev environments](guides/dev-environments.md), [tasks](guides/tasks.md), 
+    and [services](guides/services.md)
+3. See all [learning materials](../learn/index.md)
+4. Join the [Discord server](https://discord.gg/u8SmfwPpMd)
diff --git a/docs/docs/reference/dstack.yml.md b/docs/docs/reference/dstack.yml.md
@@ -0,0 +1,43 @@
+# .dstack.yml
+
+With `dstack`, you can define what you want to run as YAML configuration files 
+and run them using the `dstack run` command. 
+
+!!! info "Filename"
+    Configuration files must have a name ending with `.dstack.yml` (e.g., `.dstack.yml` or `dev.dstack.yml` are both acceptable).
+    Configuration files can be placed either in the project's root directory or in any nested folder. 
+
+Configurations can be of three types: `dev-environment`, `task`, and `service`.
+
+Below, you'll find the complete reference detailing all available properties for each type of configuration.
+
+## dev-environment
+
+This configuration type allows you to provision a [dev environment](../guides/dev-environments.md) with the required cloud resources, 
+code, and environment.
+
+#SCHEMA# dstack._internal.core.models.configurations.DevEnvironmentConfiguration
+    overrides:
+      show_root_heading: false
+      type:
+        required: true
+
+## task
+
+This configuration type allows you to run [tasks](../guides/tasks.md) like training scripts, batch jobs, or web apps.
+
+#SCHEMA# dstack._internal.core.models.configurations.TaskConfiguration
+    overrides:
+      show_root_heading: false
+      type:
+        required: true
+
+## service
+
+This configuration type allows you to deploy models or web apps as [services](../guides/services.md).
+
+#SCHEMA# dstack._internal.core.models.configurations.ServiceConfiguration
+    overrides:
+      show_root_heading: false
+      type:
+        required: true
diff --git a/docs/docs/reference/dstack.yml/dev-environment.md b/docs/docs/reference/dstack.yml/dev-environment.md
diff --git a/docs/docs/reference/dstack.yml/index.md b/docs/docs/reference/dstack.yml/index.md
diff --git a/docs/docs/reference/dstack.yml/service.md b/docs/docs/reference/dstack.yml/service.md
diff --git a/docs/docs/reference/dstack.yml/task.md b/docs/docs/reference/dstack.yml/task.md
diff --git a/docs/learn.md b/docs/learn.md
@@ -0,0 +1,9 @@
+---
+template: learn.html
+title: Learning materials
+hide:
+   - path
+   - navigation
+   - toc
+   - footer
+---
diff --git a/docs/learn/index.md b/docs/learn/index.md
@@ -1,6 +1,6 @@
 ---
 template: learn.html
-title: Learning center
+title: Learning materials
 hide:
    - navigation
    - toc