- [Docs] Updated to the new version of mkdocs-material

- [Docs] Updated `examples/python-api` (and renamed to `examples/deploy-python`)
- [Docs] Extracted `landing.html`

.github/workflows/docs.yaml

@@ -21,7 +21,7 @@ jobs:
       - run: |
           pip install pillow cairosvg
           sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
-          pip install mkdocs-material mkdocs-material-extensions mkdocs-redirects --upgrade
+          pip install mkdocs-material pip install "mkdocs-material[imaging]" mkdocs-material-extensions mkdocs-redirects --upgrade
           pip install git+https://${{ secrets.GH_TOKEN }}@github.com/squidfunk/mkdocs-material-insiders.git
           mkdocs gh-deploy --config-file ../dstack/mkdocs.yml --force
         working-directory: ./dstackai.github.io

docs/assets/stylesheets/extra.css

@@ -616,6 +616,10 @@ body {
         width: 26px;
         text-align: center;
     }
+
+    .md-nav--lifted > .md-nav__list > .md-nav__item > [for] {
+        display: none;
+    }
 }
 
 .md-sidebar--primary .md-nav__link {

docs/blog/.authors.yml

@@ -1,3 +1,5 @@
-peterschmidt85:
-  name: Andrey Cheptsov
-  avatar: https://github.com/peterschmidt85.png
+authors:
+  peterschmidt85:
+    name: Andrey Cheptsov
+    avatar: https://github.com/peterschmidt85.png
+    description: Creator

docs/blog/posts/lambda-cloud-support-preview.md

@@ -70,7 +70,7 @@ ide: vscode
     You only need to install `cuda` if you intend to build a custom CUDA kernel. Otherwise, it is not necessary as the
     essential CUDA drivers are already pre-installed.
 
-The [documentation](../../docs) and [examples](https://github.com/dstackai/dstack-examples/blob/main/README.md)
+The [documentation](../../docs/index.md) and [examples](../../examples/index.md)
 are updated to reflect the changes.
 
 !!! info "Give it a try and share feedback"

docs/blog/posts/new-configuration-format-and-cli-experience.md

@@ -160,7 +160,7 @@ Last but not least, here's a brief list of other improvements:
    configured on the machine where the server is running).
  * We've introduced a new Python API and UI for working with artifacts (more details to come later this week).
 
-The [documentation](../../docs) and [examples](https://github.com/dstackai/dstack-examples/blob/main/README.md)
+The [documentation](../../docs/index.md) and [examples](../../examples/index.md)
 are updated to reflect the changes.
 
 !!! info "Try the update and share feedback"

docs/blog/posts/prebuilt-environments-spot-and-retry-policies.md

@@ -96,9 +96,9 @@ Other improvements in this release:
 - Deletion of repositories is now possible through the UI. 
 - When running a dev environment from a Git repo, you can now pull and push changes directly from the dev environment,
   with `dstack` correctly configuring your Git credentials.
-- The newly added Python API for working with artifacts is now documented [here](../../docs/reference/api/python.md).
+- The newly added Python API for working with artifacts is now documented [here](../../docs/reference/api/python/index.md).
 
-The [documentation](../../docs) and [examples](https://github.com/dstackai/dstack-examples/blob/main/README.md)
+The [documentation](../../docs/index.md) and [examples](../../examples/index.md)
 are updated to reflect the changes.
 
 !!! info "Give it a try and share feedback"

docs/docs/guides/clouds.md

@@ -49,16 +49,16 @@ Configuring backends involves providing cloud credentials, and specifying storag
 <div class="grid cards" markdown>
 - [**AWS**
    Learn how to set up an Amazon Web Services backend.
-  ](../../reference/backends/aws/)
+  ](../reference/backends/aws.md)
 - [**GCP**
-   Learn how to set up a Google Cloud backend.
-  ](../../reference/backends/gcp/)
+Learn how to set up a Google Cloud backend.
+  ](../reference/backends/gcp.md)
 - [**Azure**
    Learn how to set up an Microsoft Azure backend.
-  ](../../reference/backends/azure/)
+  ](../reference/backends/azure.md)
 - [**Lambda**
    Learn how to set up a Lambda Cloud backend.
-  ](../../reference/backends/lambda/)
+  ](../reference/backends/lambda.md)
 
 </div>
 

docs/docs/reference/api/python/index.md

@@ -5,7 +5,7 @@ The Python API allows for programmatically running tasks and services across con
 #### Installation
 
 Before you can use `dstack` Python API, ensure you have installed the `dstack` package, 
-started a `dstack` server with [configured clouds](../../docs/docs/guides/clouds.md).
+started a `dstack` server with [configured clouds](../../../guides/clouds.md).
 
 ```shell
 pip install "dstack[all]==0.11.3rc1"

docs/examples/deploy-python.md

@@ -0,0 +1,150 @@
+# Deploying LLMs using Python API
+
+The [Python API](../docs/reference/api/python/index.md) of `dstack` can be used to run [tasks](../docs/guides/tasks.md) and [services](../docs/guides/services.md) programmatically.
+
+To demonstrate how it works, we've created a simple Streamlit app that uses `dstack`'s API to deploy a quantized 
+version of Llama 2 to your cloud with a click of a button.
+
+![](images/python-api/dstack-python-api-streamlit-example.png){ width=800 }
+
+## Prerequisites
+
+Before you can use `dstack` Python API, ensure you have installed the `dstack` package, 
+started a `dstack` server with [configured clouds](../docs/guides/clouds.md).
+
+```shell
+pip install "dstack[all]==0.11.3rc1"  
+dstack start
+```
+
+## How does it work?
+
+### Create a client
+
+If you're familiar with Docker's Python SDK, you'll find `dstack`'s [Python API](../docs/reference/api/python/index.md) 
+quite similar, except that it runs your workload in the cloud.
+
+To get started, create an instance of `dstack.Client` and use its methods to submit and manage runs.
+
+```python
+import dstack
+
+try:
+    client = dstack.Client.from_config(repo_dir=".")
+except dstack.api.hub.errors.HubClientError as e:
+    print(e)
+```
+
+### Create a task
+
+!!! info "NOTE:"
+    With `dstack.Client`, you can run [tasks](../docs/guides/tasks.md) and [services](../docs/guides/services.md).
+    Running a task allows you to programmatically access its ports and
+    forward traffic to your local machine. For example, if you run an LLM as a task, you can access it on `localhost`.
+    Services on the other hand allow deploying applications as public endpoints.
+
+In our example, we'll deploy an LLM as a task. To do this, we'll create a `dstack.Task` instance that configures how the
+LLM should be run.
+
+```python
+configuration = dstack.Task(
+    image="ghcr.io/huggingface/text-generation-inference:latest",
+    env={"MODEL_ID": model_id},
+    commands=[
+        "text-generation-launcher --trust-remote-code --quantize gptq",
+    ],
+    ports=["8080:80"],  # LLM runs on port 80, forwarded to localhost:8080
+)
+```
+
+### Create resources
+
+Then, we'll need to specify the resources our LLM will require. To do this, we'll create a `dstack.Resources` instance:
+
+```python
+
+if model_id == "TheBloke/Llama-2-13B-chat-GPTQ":
+    gpu_memory = "20GB"
+elif model_id == "TheBloke/Llama-2-70B-chat-GPTQ":
+    gpu_memory = "40GB"
+
+resources = dstack.Resources(gpu=dstack.GPU(memory=gpu_memory))
+```
+
+### Submit the run
+
+To deploy the LLM, we submit the task using `runs.submit()` in `dstack.Client`.
+
+```python
+run_name = "deploy-python"
+
+run = client.runs.submit(configuration=configuration, run_name=run_name, resources=resources)
+```
+
+### Attach to the run
+
+Then, we use the `attach()` method on `dstack.Run`. This method waits for the task to start, 
+and forwards the configured ports to `localhost`.
+
+```
+run.attach()
+```
+
+### Wait for the endpoint to start
+
+Finally, we wait until `http://localhost:8080/health` returns `200`, which indicates that the LLM is deployed and ready to
+handle requests.
+
+```python
+import time
+import requests
+
+while True:
+    time.sleep(0.5)
+    try:
+        r = requests.get("http://localhost:8080/health")
+        if r.status_code == 200:
+            break
+    except Exception:
+        pass
+```
+
+### Stop the run
+
+To undeploy the model, we can use the `stop()` method on `dstack.Run`.
+
+```python
+run.stop()
+```
+
+### Retrieve the status of a run
+
+Note: If you'd like to retrieve the `dstack.Run` instance by the name of the run,
+you can use the `runs.get()` method on `dstack.Client`.
+
+```python
+run = client.runs.get(run_name)
+```
+
+The `status()` method on `dstack.Run` can always provide the status of the run.
+
+```python
+if run:
+    print(run.status())
+```
+
+## Source code
+
+The complete, ready-to-run code is available in [dstackai/dstack-examples](https://github.com/dstackai/dstack-examples).
+
+```shell
+git clone https://github.com/dstackai/dstack-examples
+cd dstack-examples
+```
+
+Once the repository is cloned, feel free to install the requirements and run the app:
+
+```
+pip install -r deploy-python/requirements.txt
+streamlit run deploy-python/app.py
+```