docs: remove howtos and add references (#438)

Remove most how-to docs since they are more like references. Create reference docs. Changes: - almost all how-tos are removed, except: - how to install (newly created) - how to manage service dependencies (will rework soon) - how-tos are moved to references, all are updated using the template provided by Anne. Most reference is a single page, some are grouped together (like changes and tasks, pebble exec and file management commands, notices/notice/notify). - refactor the tutorial after changing links for how-tos and references. --------- Co-authored-by: Ben Hoyt <benhoyt@gmail.com>
canonical · Jul 23, 2024 · 4300038 · 4300038
1 parent 6bbc91a
commit 4300038
Show file tree

Hide file tree

Showing 36 changed files with 902 additions and 304 deletions.
diff --git a/docs/how-to/changes-and-tasks.md b/docs/how-to/changes-and-tasks.md
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -5,16 +5,5 @@
 :maxdepth: 1
 
 Install Pebble <install-pebble>
-Run the daemon <run-the-daemon>
-View, start, stop services <view-start-stop-services>
-Update and restart services <update-restart-services>
 Manage service dependencies <service-dependencies>
-Configure service auto-restart <service-auto-restart>
-Use health checks <health-checks>
-Use changes and tasks <changes-and-tasks>
-Get logs <logs>
-Use log forwarding <log-forwarding>
-Use notices <notices>
-Configure layers <configure-layers>
-Use Pebble in containers <pebble-in-containers>
 ```
diff --git a/docs/how-to/notices.md b/docs/how-to/notices.md
diff --git a/docs/how-to/pebble-in-containers.md b/docs/how-to/pebble-in-containers.md
diff --git a/docs/how-to/run-the-daemon.md b/docs/how-to/run-the-daemon.md
diff --git a/docs/how-to/update-restart-services.md b/docs/how-to/update-restart-services.md
diff --git a/docs/how-to/view-start-stop-services.md b/docs/how-to/view-start-stop-services.md
diff --git a/docs/reference/changes-and-tasks/changes-and-tasks.md b/docs/reference/changes-and-tasks/changes-and-tasks.md
@@ -0,0 +1,17 @@
+# Changes and tasks
+
+When Pebble performs a (potentially invasive or long-running) operation such as starting or stopping a service, it records a "change" object with one or more "tasks" in it.
+
+## How it works
+
+The daemon records this state in a JSON file on disk at `$PEBBLE/.pebble.state`.
+
+## Commands
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+Changes command <pebble-changes>
+Tasks command <pebble-tasks>
+```
diff --git a/docs/reference/changes-and-tasks/pebble-changes.md b/docs/reference/changes-and-tasks/pebble-changes.md
@@ -0,0 +1,30 @@
+# Pebble changes command
+
+The changes command displays a summary of system changes performed recently.
+
+## Usage
+
+To see recent changes, for this or previous server runs, use `pebble changes`:
+
+```{terminal}
+ :input: pebble changes --help
+Usage:
+ pebble changes [changes-OPTIONS] [<service>]
+
+The changes command displays a summary of system changes performed recently.
+
+[changes command options]
+ --abs-time Display absolute times (in RFC 3339 format). Otherwise, display relative times up to 60 days, then YYYY-MM-DD.
+```
+
+## Examples
+
+Here is an example of `pebble changes`. You should get output similar to this:
+
+```
+$ pebble changes
+ID Status Spawn Ready Summary
+1 Done today at 14:33 NZDT today at 14:33 NZDT Autostart service "srv1"
+2 Done today at 15:26 NZDT today at 15:26 NZDT Start service "srv2"
+3 Done today at 15:26 NZDT today at 15:26 NZDT Stop service "srv1" and 1 more
+```
diff --git a/docs/reference/changes-and-tasks/pebble-tasks.md b/docs/reference/changes-and-tasks/pebble-tasks.md
@@ -0,0 +1,36 @@
+# Pebble tasks command
+
+The tasks command displays a summary of tasks associated with an individual change that happened recently.
+
+## Usage
+
+To drill down and see the tasks that make up a change, use `pebble tasks <change-id>`:
+
+```{terminal}
+ :input: pebble tasks --help
+Usage:
+ pebble tasks [tasks-OPTIONS] [<change-id>]
+
+The tasks command displays a summary of tasks associated with an individual
+change that happened recently.
+
+[tasks command options]
+ --abs-time Display absolute times (in RFC 3339 format). Otherwise, display relative times up to 60 days, then YYYY-MM-DD.
+ --last= Select last change of given type (install, refresh, remove, try, auto-refresh, etc.). A question mark at the end of the type means
+ to do nothing (instead of returning an error) if no change of the given type is found. Note the question mark could need protecting
+ from the shell.
+
+[tasks command arguments]
+ <change-id>: Change ID
+```
+
+## Examples
+
+To view tasks from change-id 3, run:
+
+```{terminal}
+ :input: pebble tasks 3
+Status Spawn Ready Summary
+Done today at 15:26 NZDT today at 15:26 NZDT Stop service "srv1"
+Done today at 15:26 NZDT today at 15:26 NZDT Stop service "srv2"
+```
diff --git a/docs/reference/cli-commands/cli-commands.md b/docs/reference/cli-commands/cli-commands.md
@@ -0,0 +1,14 @@
+# CLI Commands
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+help <help>
+logs <logs>
+replan <replan>
+run <run>
+services <services>
+start <start>
+stop <stop>
+```
diff --git a/docs/reference/pebble-help.md → docs/reference/cli-commands/help.md b/docs/reference/pebble-help.md → docs/reference/cli-commands/help.md