docs: add workspace docs to book

Signed-off-by: Andrius Pukšta <andrius.puksta@sensmetry.com>

Author: andrius-puksta-sensmetry

docs/book.toml

@@ -5,3 +5,8 @@ language = "en"
 
 [build]
 build-dir = "book"
+create-missing = false
+
+[output.html]
+additional-css = ["theme/style.css"]
+git-repository-url = "https://github.com/sensmetry/sysand"

docs/src/SUMMARY.md

@@ -4,6 +4,7 @@
   - [Installation](getting_started/installation.md)
   - [Tutorial](getting_started/tutorial.md)
 - [Project metadata](metadata.md)
+- [Workspaces](workspaces.md)
 - [Commands](commands.md)
   - [sysand init](commands/init.md)
   - [sysand add](commands/add.md)

docs/src/workspaces.md

@@ -0,0 +1,73 @@
+# Workspaces
+
+<div class="warning">
+
+Warning:
+Workspace support is experimental and may change or be removed in any release.
+See [workspaces tracking issue](https://github.com/sensmetry/sysand/issues/101)
+for planned functionality and changes
+
+</div>
+
+## Introduction
+
+It is common to have multiple related projects that are all developed together
+and that usually use each other's functionality.
+
+Sysand supports such uses with workspaces. A workspace is a collection of
+projects, commonly structured like this:
+
+```plain
+workspace
+ ├──project_1
+ ├──project_2
+ └──project_3
+```
+
+Such a structure is not a requirement, though. Projects can be anywhere
+under the workspace root directory.
+
+## Defining a workspace
+
+A workspace is defined by `.workspace.json` file in the root directory of
+the workspace.
+
+`.workspace.json` contains a JSON object. The only currently permitted key
+is `projects`, for which the value is an array of objects having two keys:
+
+- `path`: A Unix-style path relative to workspace root, specifying the
+  project's directory
+- `iris`: An array of IRIs identifying the project. The IRIs can be freely
+  chosen, but reasonable care has to be taken to make them not clash with
+  possible IRIs of third party projects. Any of the included IRIs can be
+  used to refer to the project from other projects in the workspace
+  instead of using `file://` URLs
+
+## Example
+
+An example `.workspace.json` file:
+
+```json
+{
+    "projects": [
+        {
+            "path": "projectGroup1/project1",
+            "iris": [
+                "urn:local:project1"
+            ]
+        },
+        {
+            "path": "projectGroup1/project2",
+            "iris": [
+                "urn:local:project2"
+            ]
+        },
+        {
+            "path": "project3",
+            "iris": [
+                "urn:local:project3"
+            ]
+        }
+    ]
+}
+```

docs/theme/style.css

@@ -0,0 +1,33 @@
+/*
+Taken from Rust reference.
+Warnings and notes:
+Write the <div>s on their own line. E.g.
+<div class="warning">
+Warning: This is bad!
+</div>
+*/
+main .warning p {
+    padding: 10px 20px;
+    margin: 20px 0;
+}
+
+main .warning p::before {
+    content: "⚠️ ";
+}
+
+.light main .warning p,
+.rust main .warning p {
+    border: 2px solid red;
+    background: #ffcece;
+}
+
+.rust main .warning p {
+    /* overrides previous declaration */
+    border-color: #961717;
+}
+
+.coal main .warning p,
+.navy main .warning p,
+.ayu main .warning p {
+    background: #542626
+}