Refactor automation documentation

matifali · matifali · commit 60169967694b · 2024-09-10T16:15:20.000Z
Relocate automation documentation to the reference section to improve
the organization of the docs. This makes the reference section the
go-to place for automation-related capabilities in Coder.

Changes:
- Moved and deleted `automation.md` from the admin section.
- Updated `manifest.json` to remove the automation entry.
- Transferred content from `automation.md` to `reference/README.md`.

This improves documentation accessibility and organizational clarity.
diff --git a/docs/admin/automation.md b/docs/admin/automation.md
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -465,12 +465,6 @@
 							"path": "./admin/security/secrets.md"
 						}
 					]
-				},
-				{
-					"title": "Automation",
-					"description": "DIfferent ways to automate Coder actions and workflows",
-					"path": "./admin/automation.md",
-					"icon_path": "./images/icons/plug.svg"
 				}
 			]
 		},
diff --git a/docs/reference/README.md b/docs/reference/README.md
@@ -1,7 +1,110 @@
 # Reference
 
-Autogenerated documentation around Coder.
+# Automation
 
-- [REST API](./api)
-- [Command Line](./cli)
-- [Agent API](./agent-api)
+All actions possible through the Coder dashboard can also be automated. There are several ways to extend/automate
+Coder:
+
+- [coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest)
+- [CLI](../reference/cli/README.md)
+- [REST API](../reference/api/README.md)
+- [Coder SDK](https://pkg.go.dev/github.com/coder/coder/v2/codersdk)
+- [Agent API](../reference/agent-api/README.md)
+
+## Quickstart
+
+Generate a token on your Coder deployment by visiting:
+
+```shell
+https://coder.example.com/settings/tokens
+```
+
+List your workspaces
+
+```shell
+# CLI
+coder ls \
+  --url https://coder.example.com \
+  --token <your-token> \
+  --output json
+
+# REST API (with curl)
+curl https://coder.example.com/api/v2/workspaces?q=owner:me \
+  -H "Coder-Session-Token: <your-token>"
+```
+
+## Documentation
+
+We publish an [API reference](../reference/api/README.md) in our documentation.
+You can also enable a
+[Swagger endpoint](../reference/cli/server.md#--swagger-enable) on your Coder
+deployment.
+
+## Use cases
+
+We strive to keep the following use cases up to date, but please note that
+changes to API queries and routes can occur. For the most recent queries and
+payloads, we recommend checking the relevant documentation.
+
+### Users & Groups
+
+- [Manage Users via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/user)
+- [Manage Groups via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/group)
+
+### Templates
+
+- [Manage templates via Terraform or CLI](../admin/templates/managing-templates/change-management.md):
+  Store all templates in git and update them in CI/CD pipelines.
+
+### Workspace agents
+
+Workspace agents have a special token that can send logs, metrics, and workspace
+activity.
+
+- [Custom workspace logs](../reference/api/agents.md#patch-workspace-agent-logs):
+  Expose messages prior to the Coder init script running (e.g. pulling image, VM
+  starting, restoring snapshot).
+  [coder-logstream-kube](https://github.com/coder/coder-logstream-kube) uses
+  this to show Kubernetes events, such as image pulls or ResourceQuota
+  restrictions.
+
+  ```shell
+  curl -X PATCH https://coder.example.com/api/v2/workspaceagents/me/logs \
+  -H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
+  -d "{
+	\"logs\": [
+	  {
+		\"created_at\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
+		\"level\": \"info\",
+		\"output\": \"Restoring workspace from snapshot: 05%...\"
+	  }
+	]
+  }"
+  ```
+
+- [Manually send workspace activity](../reference/api/agents.md#submit-workspace-agent-stats):
+  Keep a workspace "active," even if there is not an open connection (e.g. for a
+  long-running machine learning job).
+
+  ```shell
+  #!/bin/bash
+  # Send workspace activity as long as the job is still running
+
+  while true
+  do
+	if pgrep -f "my_training_script.py" > /dev/null
+	then
+	  curl -X POST "https://coder.example.com/api/v2/workspaceagents/me/report-stats" \
+	  -H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
+	  -d '{
+		"connection_count": 1
+	  }'
+
+	  # Sleep for 30 minutes (1800 seconds) if the job is running
+	  sleep 1800
+	else
+	  # Sleep for 1 minute (60 seconds) if the job is not running
+	  sleep 60
+	fi
+  done
+  ```

Original file line number	Diff line number	Diff line change
`@@ -465,12 +465,6 @@`
`465`	`465`	`"path": "./admin/security/secrets.md"`
`466`	`466`	`}`
`467`	`467`	`]`
`468`		`- },`
`469`		`- {`
`470`		`- "title": "Automation",`
`471`		`- "description": "DIfferent ways to automate Coder actions and workflows",`
`472`		`- "path": "./admin/automation.md",`
`473`		`- "icon_path": "./images/icons/plug.svg"`
`474`	`468`	`}`
`475`	`469`	`]`
`476`	`470`	`},`