docs: restructure references (#461)

Structural changes to the reference docs.

docs/generate_command_docs.py

@@ -44,7 +44,16 @@ def get_all_commands() -> typing.List[typing.Tuple[str, str]]:
 
 
 def get_command_help_output(cmd: typing.List[str]) -> str:
-    return subprocess.run(cmd, text=True, capture_output=True, check=True).stdout
+    # Set a fixed terminal line columns so that the output won't be
+    # affected by the actual terminal width.
+    cmd = f"stty cols 80; {cmd}"
+    return subprocess.run(
+        cmd,
+        shell=True,
+        text=True,
+        capture_output=True,
+        check=True,
+    ).stdout
 
 
 def render_code_block_cmd(text: str, cmd: str) -> str:
@@ -93,7 +102,7 @@ def create_file_if_not_exist(filepath: str, cmd: str) -> bool:
 def generate_help_command_and_output(cmd: str) -> typing.Tuple[str, str]:
     help_cmd = ["pebble", "help"] if cmd == "help" else ["pebble", cmd, "--help"]
     help_cmd_str = " ".join(help_cmd)
-    help_cmd_output = get_command_help_output(help_cmd).strip()
+    help_cmd_output = get_command_help_output(help_cmd_str).strip()
 
     output = f"""\
 <!-- START AUTOMATED OUTPUT -->

docs/how-to/service-dependencies.md

@@ -262,7 +262,5 @@ failed run.
 - [pebble services command](../reference/cli-commands/services.md)
 - [pebble start command](../reference/cli-commands/start.md)
 - [pebble stop command](../reference/cli-commands/stop.md)
-- [Changes and tasks](../reference/changes-and-tasks/changes-and-tasks.md)
 - [Layer specification](../reference/layer-specification.md)
-
-[Changes and tasks]: /reference/changes-and-tasks/changes-and-tasks.md
+- [Changes and tasks](/reference/changes-and-tasks.md).

docs/reference/changes-and-tasks/changes-and-tasks.md → docs/reference/changes-and-tasks.md

@@ -8,10 +8,5 @@ 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>
-```
+- {ref}`reference_pebble_changes_command`
+- {ref}`reference_pebble_tasks_command`

docs/reference/cli-commands/add.md

@@ -17,6 +17,7 @@ is specified, combine the layer with an existing layer that has the given
 label (or append if the label is not found).
 
 [add command options]
-      --combine         Combine the new layer with an existing layer that has the given label (default is to append)
+      --combine         Combine the new layer with an existing layer that has
+                        the given label (default is to append)
 ```
 <!-- END AUTOMATED OUTPUT -->

docs/reference/cli-commands/changes.md

@@ -14,6 +14,21 @@ Usage:
 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.
+      --abs-time     Display absolute times (in RFC 3339 format). Otherwise,
+                     display relative times up to 60 days, then YYYY-MM-DD.
 ```
 <!-- END AUTOMATED OUTPUT -->
+
+## 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
+```
+
+Read more: [Changes and tasks](../changes-and-tasks.md).

docs/reference/cli-commands/exec.md

@@ -24,14 +24,43 @@ pebble exec --timeout 10s -- echo -n foo bar
       -w=              Working directory to run command in
           --env=       Environment variable to set (in 'FOO=bar' format)
           --uid=       User ID to run command as
-          --user=      Username to run command as (user's UID must match uid if both present)
+          --user=      Username to run command as (user's UID must match uid if
+                       both present)
           --gid=       Group ID to run command as
-          --group=     Group name to run command as (group's GID must match gid if both present)
+          --group=     Group name to run command as (group's GID must match gid
+                       if both present)
           --timeout=   Timeout after which to terminate command
-          --context=   Inherit the context of the named service (overridden by -w, --env, --uid/user, --gid/group)
-      -t               Allocate remote pseudo-terminal and connect stdout to it (default if stdout is a TTY)
+          --context=   Inherit the context of the named service (overridden by
+                       -w, --env, --uid/user, --gid/group)
+      -t               Allocate remote pseudo-terminal and connect stdout to it
+                       (default if stdout is a TTY)
       -T               Disable remote pseudo-terminal allocation
-      -i               Interactive mode: connect stdin to the pseudo-terminal (default if stdin and stdout are TTYs)
+      -i               Interactive mode: connect stdin to the pseudo-terminal
+                       (default if stdin and stdout are TTYs)
       -I               Disable interactive mode and use a pipe for stdin
 ```
 <!-- END AUTOMATED OUTPUT -->
+
+## Examples
+
+For example, you could use `exec` to run `pg_dump` and create a PostgreSQL database backup:
+
+```{terminal}
+   :input: pebble exec pg_dump mydb
+--
+-- PostgreSQL database dump
+--
+...
+```
+
+The exec feature uses WebSockets under the hood, and allows you to stream stdin to the process, as well as stream stdout and stderr back. When running `pebble exec`, you can specify the working directory to run in (`-w`), environment variables to set (`--env`), and the user and group to run as (`--uid`/`--user` and `--gid`/`--group`).
+
+You can also apply a timeout with `--timeout`, for example:
+
+```{terminal}
+   :input: pebble exec --timeout 1s -- sleep 3
+error: cannot perform the following tasks:
+- exec command "sleep" (timed out after 1s: context deadline exceeded)
+```
+
+Read more: [Use Pebble in containers](../pebble-in-containers.md).

docs/reference/cli-commands/logs.md

@@ -21,7 +21,8 @@ if none are specified) and displays them in chronological order.
                        pressed. If no services are specified, show logs from
                        all services running when the command starts.
           --format=    Output format: "text" (default) or "json" (JSON lines).
-      -n=              Number of logs to show (before following); defaults to 30.
+      -n=              Number of logs to show (before following); defaults to
+                       30.
                        If 'all', show all buffered logs.
 ```
 <!-- END AUTOMATED OUTPUT -->

docs/reference/cli-commands/ls.md

@@ -11,12 +11,16 @@ The `ls` command is used to list path contents.
 Usage:
   pebble ls [ls-OPTIONS] <path>
 
-The ls command lists entries in the filesystem at the specified path. A glob pattern
+The ls command lists entries in the filesystem at the specified path. A glob
+pattern
 may be specified for the last path element.
 
 [ls command options]
-          --abs-time  Display absolute times (in RFC 3339 format). Otherwise, display relative times up to 60 days, then YYYY-MM-DD.
+          --abs-time  Display absolute times (in RFC 3339 format). Otherwise,
+                      display relative times up to 60 days, then YYYY-MM-DD.
       -d              List matching entries themselves, not directory contents
       -l              Use a long listing format
 ```
 <!-- END AUTOMATED OUTPUT -->
+
+Read more: [Use Pebble in containers](../pebble-in-containers.md).

docs/reference/cli-commands/mkdir.md

@@ -14,11 +14,14 @@ Usage:
 The mkdir command creates the specified directory.
 
 [mkdir command options]
-      -p            Create parent directories as needed, and don't fail if path already exists
+      -p            Create parent directories as needed, and don't fail if path
+                    already exists
       -m=           Override mode bits (3-digit octal)
           --uid=    Use specified user ID
           --user=   Use specified username
           --gid=    Use specified group ID
           --group=  Use specified group name
 ```
 <!-- END AUTOMATED OUTPUT -->
+
+Read more: [Use Pebble in containers](../pebble-in-containers.md).

docs/reference/cli-commands/notice.md

@@ -15,6 +15,46 @@ The notice command fetches a single notice, either by ID (1-arg variant), or
 by unique type and key combination (2-arg variant).
 
 [notice command options]
-      --uid=            Look up notice from user with this UID (admin only; 2-arg variant only)
+      --uid=            Look up notice from user with this UID (admin only;
+                        2-arg variant only)
 ```
 <!-- END AUTOMATED OUTPUT -->
+
+## Examples
+
+You can fetch a notice either by ID or by type/key combination.
+
+ To fetch the notice with ID "1":
+
+```{terminal}
+   :input: pebble notice 1
+id: "1"
+user-id: 1000
+type: custom
+key: example.com/foo
+first-occurred: 2023-09-15T04:16:09.179395298Z
+last-occurred: 2023-09-15T04:16:19.487035209Z
+last-repeated: 2023-09-15T04:16:09.179395298Z
+occurrences: 3
+expire-after: 168h0m0s
+```
+
+To fetch the notice with type "custom" and key "example.com<span></span>/bar":
+
+```{terminal}
+   :input: pebble notice custom other.com/bar
+id: "2"
+user-id: public
+type: custom
+key: other.com/bar
+first-occurred: 2023-09-15T04:16:17.180049768Z
+last-occurred: 2023-09-15T04:16:17.180049768Z
+last-repeated: 2023-09-15T04:16:17.180049768Z
+occurrences: 1
+last-data:
+    name: value
+    email: john@smith.com
+expire-after: 168h0m0s
+```
+
+Read more: [Notices](../notices.md).

docs/reference/cli-commands/notices.md

@@ -21,11 +21,27 @@ can use --users=all to view notice with any user ID, or --uid=UID to view
 another user's notices.
 
 [notices command options]
-      --abs-time    Display absolute times (in RFC 3339 format). Otherwise, display relative times up to 60 days, then YYYY-MM-DD.
-      --users=      The only valid value is 'all', which lists notices with any user ID (admin only; cannot be used with --uid)
-      --uid=        Only list notices with this user ID (admin only; cannot be used with --users)
+      --abs-time    Display absolute times (in RFC 3339 format). Otherwise,
+                    display relative times up to 60 days, then YYYY-MM-DD.
+      --users=      The only valid value is 'all', which lists notices with any
+                    user ID (admin only; cannot be used with --uid)
+      --uid=        Only list notices with this user ID (admin only; cannot be
+                    used with --users)
       --type=       Only list notices of this type (multiple allowed)
       --key=        Only list notices with this key (multiple allowed)
       --timeout=    Wait up to this duration for matching notices to arrive
 ```
 <!-- END AUTOMATED OUTPUT -->
+
+## Examples
+
+To fetch all notices:
+
+```{terminal}
+   :input: pebble notices
+ID   User    Type    Key              First                Repeated             Occurrences
+1    1000    custom  example.com/foo  today at 16:16 NZST  today at 16:16 NZST  3
+2    public  custom  other.com/bar    today at 16:16 NZST  today at 16:16 NZST  1
+```
+
+Read more: [Notices](../notices.md).

docs/reference/cli-commands/notify.md

@@ -15,6 +15,25 @@ The notify command records a custom notice with the specified key and optional
 data fields.
 
 [notify command options]
-      --repeat-after=   Prevent notice with same type and key from reoccurring within this duration
+      --repeat-after=   Prevent notice with same type and key from reoccurring
+                        within this duration
 ```
 <!-- END AUTOMATED OUTPUT -->
+
+## Examples
+
+To record `custom` notices, use `pebble notify` -- the notice user ID will be set to the client's user ID:
+
+```{terminal}
+   :input: pebble notify example.com/foo
+Recorded notice 1
+```
+
+Notify with two data fields:
+
+```{terminal}
+   :input: pebble notify other.com/bar name=value email=john@smith.com  
+Recorded notice 2
+```
+
+Read more: [Notices](../notices.md).

docs/reference/cli-commands/pull.md

@@ -14,3 +14,5 @@ Usage:
 The pull command retrieves a file from the remote system.
 ```
 <!-- END AUTOMATED OUTPUT -->
+
+Read more: [Use Pebble in containers](../pebble-in-containers.md).

docs/reference/cli-commands/push.md

@@ -22,3 +22,5 @@ The push command transfers a file to the remote system.
           --group=         Use specified group name
 ```
 <!-- END AUTOMATED OUTPUT -->
+
+Read more: [Use Pebble in containers](../pebble-in-containers.md).

docs/reference/cli-commands/replan.md

@@ -16,7 +16,8 @@ so that running services exactly match the desired configuration in the
 current plan.
 
 [replan command options]
-      --no-wait    Do not wait for the operation to finish but just print the change id.
+      --no-wait    Do not wait for the operation to finish but just print the
+                   change id.
 ```
 <!-- END AUTOMATED OUTPUT -->
 

docs/reference/cli-commands/restart.md

@@ -14,6 +14,7 @@ Usage:
 The restart command restarts the named service(s) in the correct order.
 
 [restart command options]
-      --no-wait      Do not wait for the operation to finish but just print the change id.
+      --no-wait      Do not wait for the operation to finish but just print the
+                     change id.
 ```
 <!-- END AUTOMATED OUTPUT -->

docs/reference/cli-commands/rm.md

@@ -14,6 +14,9 @@ Usage:
 The rm command removes a file or directory.
 
 [rm command options]
-      -r            Remove all files and directories recursively in the specified path
+      -r            Remove all files and directories recursively in the
+                    specified path
 ```
 <!-- END AUTOMATED OUTPUT -->
+
+Read more: [Use Pebble in containers](../pebble-in-containers.md).