chore: minor improvement to docs generation (#477)

Minor fix to the automated doc generation.

.github/workflows/tests.yml

@@ -70,3 +70,24 @@ jobs:
       run: |
         go fmt ./...
         git diff --exit-code
+
+  docs:
+    runs-on: ubuntu-latest
+
+    name: Automated docs check
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12' 
+
+    - name: Install tox
+      run: pip install tox~=4.17
+
+    - name: Ensure no CLI reference doc changes
+      run: |
+        tox -e commands
+        git diff --exit-code
+      working-directory: ./docs

docs/generate_command_docs.py

@@ -43,7 +43,7 @@ def get_all_commands() -> typing.List[typing.Tuple[str, str]]:
     )
 
 
-def get_command_help_output(cmd: typing.List[str]) -> str:
+def get_command_help_output(cmd: str) -> str:
     # 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}"
@@ -100,9 +100,10 @@ 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_str).strip()
+    args = ["help"] if cmd == "help" else [cmd, "--help"]
+    help_cmd_str = " ".join(["pebble"] + args)
+    go_run_cmd = " ".join(["go", "run", "../cmd/pebble"] + args)
+    help_cmd_output = get_command_help_output(go_run_cmd).strip()
 
     output = f"""\
 <!-- START AUTOMATED OUTPUT -->
@@ -112,7 +113,7 @@ def generate_help_command_and_output(cmd: str) -> typing.Tuple[str, str]:
 ```
 <!-- END AUTOMATED OUTPUT -->"""
 
-    return help_cmd, output
+    return help_cmd_str, output
 
 
 def process_command(cmd: str, description: str):

docs/reference/cli-commands/run.md

@@ -14,12 +14,9 @@ Usage:
 The run command starts Pebble and runs the configured environment.
 
 Additional arguments may be provided to the service command with the --args
-option, which
-must be terminated with ";" unless there are no further program options.  These
-arguments
-are appended to the end of the service command, and replace any default
-arguments defined
-in the service plan. For example:
+option, which must be terminated with ";" unless there are no further program
+options. These arguments are appended to the end of the service command, and
+replace any default arguments defined in the service plan. For example:
 
 pebble run --args myservice --port 8080 \; --hold
 

docs/reference/cli-commands/warnings.md

@@ -14,9 +14,8 @@ Usage:
 The warnings command lists the warnings that have been reported to the system.
 
 Once warnings have been listed with 'pebble warnings', 'pebble okay' may be
-used to
-silence them. A warning that's been silenced in this way will not be listed
-again unless it happens again, _and_ a cooldown time has passed.
+used to silence them. A warning that's been silenced in this way will not be
+listed again unless it happens again, _and_ a cooldown time has passed.
 
 Warnings expire automatically, and once expired they are forgotten.