docs: configuring multi and single root workspaces (#2720)

* docs: configuring multi and single root workspaces Signed-off-by: Vitaliy Gulyy <[email protected]> * docs: configuring multi and single root workspaces Signed-off-by: Vitaliy Gulyy <[email protected]> * Update modules/administration-guide/pages/configuring-microsoft-visual-studio-code.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-microsoft-visual-studio-code.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Jana Vrbkova <[email protected]> * docs: configuring multi and single root workspaces Signed-off-by: Vitaliy Gulyy <[email protected]> * docs: configuring multi and single root workspaces Signed-off-by: Vitaliy Gulyy <[email protected]> * docs: configuring multi and single root workspaces Signed-off-by: Vitaliy Gulyy <[email protected]> * docs: configuring multi and single root workspaces Signed-off-by: Vitaliy Gulyy <[email protected]> * Update modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc Co-authored-by: Ilya Buziuk <[email protected]> * docs: configuring multi and single root workspaces Signed-off-by: Vitaliy Gulyy <[email protected]> * docs: configuring multi and single root workspaces Signed-off-by: Vitaliy Gulyy <[email protected]> --------- Signed-off-by: Vitaliy Gulyy <[email protected]> Co-authored-by: Jana Vrbkova <[email protected]> Co-authored-by: Ilya Buziuk <[email protected]>
eclipse-che · Apr 22, 2024 · fd4a72c · fd4a72c
1 parent 81ad19d
commit fd4a72c
Show file tree

Hide file tree

Showing 3 changed files with 105 additions and 0 deletions.
diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc
@@ -85,6 +85,8 @@
 * xref:managing-ide-extensions.adoc[]
 ** xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[]
 ** xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[]
+* xref:configuring-visual-studio-code.adoc[]
+** xref:configuring-single-and-multiroot-workspaces.adoc[]
 * xref:managing-workloads-using-the-che-server-api.adoc[]
 * xref:upgrading-che.adoc[]
 ** xref:upgrading-the-chectl-management-tool.adoc[]

diff --git a/...les/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc b/...les/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc
@@ -0,0 +1,91 @@
+:_content-type: PROCEDURE
+:description: Configuring single and multiroot workspaces
+:keywords: singleroot, multiroot, workspace
+:navtitle: Configuring single and multiroot workspaces
+// :page-aliases:
+
+[id="configuring-single-and-multiroot-workspaces"]
+= Configuring single and multi root workspaces
+
+With the multi-root workspace feature, you can work with multiple project folders in the same workspace. This is useful when you are working on several related projects at once, such as product documentation and product code repositories.
+
+TIP: See link:https://code.visualstudio.com/docs/editor/workspaces[What is a VS Code "workspace"] for better understanding and authoring the workspace files.
+
+[NOTE]
+====
+The workspace is set to open in multi-root mode by default.
+====
+
+Once workspace is started, the `/projects/.code-workspace` workspace file is generated. The workspace file will contain all the projects described in the devfile.
+
+[source,json]
+----
+{
+	"folders": [
+		{
+			"name": "project-1",
+			"path": "/projects/project-1"
+		},
+		{
+			"name": "project-2",
+			"path": "/projects/project-2"
+		}
+	]
+}
+----
+
+If the workspace file already exist, it will be updated and all missing projects will be taken from the devfile.
+If you remove a project from the devfile, it will be left in the workspace file.
+
+You can change the default behavior and provide your own workspace file or switch to a single-root workspace.
+
+.Procedure
+
+* Provide your own workspace file.
+
+** Put a workspace file with the name `.code-workspace` into the root of your repository. After workspace creation, the Visual Studio Code - Open Source ("Code - OSS") will use the workspace file as it is.
++
+[source,json]
+----
+{
+	"folders": [
+		{
+			"name": "project-name",
+			"path": "."
+		}
+	]
+}
+----
++
+[IMPORTANT]
+====
+Be careful when creating a workspace file. In case of errors, an empty Visual Studio Code - Open Source ("Code - OSS") will be opened instead.
+====
++
+[IMPORTANT]
+====
+If you have several projects, the workspace file will be taken from the first project.
+If the workspace file does not exist in the first project, a new one will be created and placed in the `/projects` directory. 
+====
+
+* Specify alternative workspace file.
+
+** Define the __VSCODE_DEFAULT_WORKSPACE__ environment variable in your devfile and specify the right location to the workspace file.
++
+[source,yaml]
+----
+   env:
+     - name: VSCODE_DEFAULT_WORKSPACE
+       value: "/projects/project-name/workspace-file"
+----
+
+* Open a workspace in a single-root mode.
+
+** Define __VSCODE_DEFAULT_WORKSPACE__ environment variable and set it to the root.
++
+[source,yaml]
+----
+   env:
+     - name: VSCODE_DEFAULT_WORKSPACE
+       value: "/"
+----
diff --git a/modules/administration-guide/pages/configuring-visual-studio-code.adoc b/modules/administration-guide/pages/configuring-visual-studio-code.adoc
@@ -0,0 +1,12 @@
+:_content-type: CONCEPT
+:description: Configuring Visual Studio Code - Open Source ("Code - OSS")
+:keywords: vscode, workspace
+:navtitle: Configuring Visual Studio Code - Open Source ("Code - OSS")
+//:page-aliases:
+
+[id="configuring-visual-studio-code"]
+= Configuring Visual Studio Code - Open Source ("Code - OSS")
+
+Learn how to configure Visual Studio Code - Open Source ("Code - OSS").
+
+* xref:configuring-single-and-multiroot-workspaces.adoc[]