[Docs] Update to the latest mkdocs-material and add the contributing/DOCS.md (#3286)

Author: peterschmidt85

.github/workflows/build-docs.yml

@@ -2,10 +2,6 @@ name: Build Docs
 
 on:
   workflow_call:
-    inputs:
-      release-tag:
-        type: string
-        required: false
 
 jobs:
   build-docs:
@@ -17,18 +13,10 @@ jobs:
           python-version: 3.11
       - name: Install dstack
         run: |
-          uv pip install examples/plugins/example_plugin_server
-          if [ -n "${{ inputs.release-tag }}" ]; then
-            uv pip install "dstack[server]==${{ inputs.release-tag }}"
-          else
-            uv pip install -e '.[server]'
-          fi
+          uv sync --extra server
       - name: Build
         run: |
-          uv pip install pillow cairosvg
           sudo apt-get update && sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
-          uv pip install mkdocs-material "mkdocs-material[imaging]" mkdocs-material-extensions mkdocs-redirects mkdocs-gen-files "mkdocstrings[python]" mkdocs-render-swagger-plugin --upgrade
-          uv pip install git+https://${{ secrets.GH_TOKEN }}@github.com/squidfunk/mkdocs-material-insiders.git
           uv run mkdocs build -s
       - uses: actions/upload-artifact@v4
         with:

.github/workflows/docs.yaml

@@ -2,15 +2,10 @@ name: Build & Deploy Docs
 
 on:
   workflow_dispatch:
-    inputs:
-      release-tag:
-        description: "dstack version"
 
 jobs:
   build-docs:
     uses: ./.github/workflows/build-docs.yml
-    with:
-      release-tag: ${{ inputs.release-tag }}
     secrets: inherit
 
   deploy-docs:

contributing/DEVELOPMENT.md

@@ -48,3 +48,7 @@ pyright -p .
 ## 6. Frontend
 
 See [FRONTEND.md](FRONTEND.md) for the details on how to build and develop the frontend.
+
+## 7. Documentation
+
+See [DOCS.md](DOCS.md) for the details on how to preview or build the documentation.

contributing/DOCS.md

@@ -0,0 +1,49 @@
+# Documentation setup
+
+## 1. Clone the repo:
+
+```shell
+git clone https://github.com/dstackai/dstack
+cd dstack
+```
+
+## 2. Install uv:
+
+https://docs.astral.sh/uv/getting-started/installation
+
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+## 3. Install `dstack` with all extras and dev dependencies:
+
+> [!WARNING]
+> Building documentation requires `python_version >= 3.11`.
+
+```shell
+uv sync --all-extras
+```
+
+`dstack` will be installed into the project's `.venv` in editable mode.
+
+## 4. (Recommended) Install pre-commit hooks:
+
+Code formatting and linting can be done automatically on each commit with `pre-commit` hooks:
+
+```shell
+uv run pre-commit install
+```
+
+## 5. Preview documentation
+
+To preview the documentation, run the follow command:
+
+```shell
+uv run mkdocs serve -w examples -s
+```
+
+If you want to build static files, you can use the following command:
+
+```shell
+uv run mkdocs build -s
+```

examples/plugins/example_plugin_server/pyproject.toml

@@ -3,9 +3,10 @@ name = "dstack-plugin-server"
 version = "0.1.0"
 description = "Example plugin server"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.9"
 dependencies = [
-    "fastapi[standard]>=0.115.12",
+    "fastapi",
+    "uvicorn",
     "dstack",
 ]
 

pyproject.toml

@@ -78,6 +78,9 @@ pattern = '<picture>\s*|<source[^>]*>\s*|\s*</picture>|<video[^>]*>\s*|</video>\
 replacement = ''
 ignore-case = true
 
+[tool.uv.sources]
+dstack-plugin-server = { path = "examples/plugins/example_plugin_server", editable = true }
+
 [tool.pyright]
 include = [
     "src/dstack/plugins",
@@ -109,6 +112,18 @@ dev = [
     "pytest-xdist>=3.6.1",
     "pyinstrument>=5.0.0",
     "kubernetes-stubs-elephant-fork",
+    # docs
+    "dstack[server]; python_version >= '3.11'",
+    "dstack-plugin-server; python_version >= '3.11'",
+    "pillow; python_version >= '3.11'",
+    "cairosvg; python_version >= '3.11'",
+    "mkdocs-material>=9.7.0; python_version >= '3.11'",
+    "mkdocs-material[imaging]; python_version >= '3.11'", 
+    "mkdocs-material-extensions; python_version >= '3.11'",
+    "mkdocs-redirects; python_version >= '3.11'",
+    "mkdocs-gen-files; python_version >= '3.11'",
+    "mkdocstrings[python]; python_version >= '3.11'", 
+    "mkdocs-render-swagger-plugin; python_version >= '3.11'",
 ]
 
 [project.optional-dependencies]