Merge pull request #2406 from buildkite/pdp-1465-fix-docs-script-that-parses-agent-help-text

Author: triarius

pages/agent/v3/help/_annotate.md

@@ -41,10 +41,12 @@ body entirely and providing a new style value.
 
 ### Example
 
-    $ buildkite-agent annotate "All tests passed! :rocket:"
-    $ cat annotation.md | buildkite-agent annotate --style "warning"
-    $ buildkite-agent annotate --style "success" --context "junit"
-    $ ./script/dynamic_annotation_generator | buildkite-agent annotate --style "success"
+```shell
+$ buildkite-agent annotate "All tests passed! :rocket:"
+$ cat annotation.md | buildkite-agent annotate --style "warning"
+$ buildkite-agent annotate --style "success" --context "junit"
+$ ./script/dynamic_annotation_generator | buildkite-agent annotate --style "success"
+```
 
 ### Options
 

pages/agent/v3/help/_annotation_remove.md

@@ -25,8 +25,10 @@ If you leave context blank, it will use the default context.
 
 ### Example
 
-    $ buildkite-agent annotation remove
-    $ buildkite-agent annotation remove --context "remove-me"
+```shell
+$ buildkite-agent annotation remove
+$ buildkite-agent annotation remove --context "remove-me"
+```
 
 ### Options
 

pages/agent/v3/help/_artifact_download.md

@@ -37,15 +37,19 @@ artifact paths.
 
 ### Example
 
-    $ buildkite-agent artifact download "pkg/*.tar.gz" . --build xxx
+```shell
+$ buildkite-agent artifact download "pkg/*.tar.gz" . --build xxx
+```
 
 This will search across all the artifacts for the build with files that match that part.
 The first argument is the search query, and the second argument is the download destination.
 
 If you're trying to download a specific file, and there are multiple artifacts from different
 jobs, you can target the particular job you want to download the artifact from:
 
-    $ buildkite-agent artifact download "pkg/*.tar.gz" . --step "tests" --build xxx
+```shell
+$ buildkite-agent artifact download "pkg/*.tar.gz" . --step "tests" --build xxx
+```
 
 You can also use the step's jobs id (provided by the environment variable $BUILDKITE_JOB_ID)
 

pages/agent/v3/help/_artifact_search.md

@@ -26,21 +26,27 @@ which will break the search.
 
 ### Example
 
-    $ buildkite-agent artifact search "pkg/*.tar.gz" --build xxx
+```shell
+$ buildkite-agent artifact search "pkg/*.tar.gz" --build xxx
+```
 
 This will search across all uploaded artifacts in a build for files that match that query.
 The first argument is the search query.
 
 If you're trying to find a specific file, and there are multiple artifacts from different
 jobs, you can target the particular job you want to search the artifacts from using --step:
 
-    $ buildkite-agent artifact search "pkg/*.tar.gz" --step "tests" --build xxx
+```shell
+$ buildkite-agent artifact search "pkg/*.tar.gz" --step "tests" --build xxx
+```
 
 You can also use the step's job id (provided by the environment variable $BUILDKITE_JOB_ID)
 
 Output formatting can be altered with the -format flag as follows:
 
-    $ buildkite-agent artifact search "*" -format "%p\n"
+```shell
+$ buildkite-agent artifact search "*" -format "%p\n"
+```
 
 The above will return a list of filenames separated by newline.
 

pages/agent/v3/help/_artifact_shasum.md

@@ -32,7 +32,9 @@ which will break the download.
 
 ### Example
 
-    $ buildkite-agent artifact shasum "pkg/release.tar.gz" --build xxx
+```shell
+$ buildkite-agent artifact shasum "pkg/release.tar.gz" --build xxx
+```
 
 This will search for all files in the build with path "pkg/release.tar.gz",
 and if exactly one match is found, the SHA-1 hash generated during upload
@@ -41,11 +43,13 @@ is printed.
 If you would like to target artifacts from a specific build step, you can do
 so by using the --step argument.
 
-    $ buildkite-agent artifact shasum "pkg/release.tar.gz" --step "release" --build xxx
+```shell
+$ buildkite-agent artifact shasum "pkg/release.tar.gz" --step "release" --build xxx
+```
 
 You can also use the step's job ID (provided by the environment variable $BUILDKITE_JOB_ID)
 
-The --sha256 argument requests SHA-256 instead of SHA-1; this is only
+The `--sha256` argument requests SHA-256 instead of SHA-1; this is only
 available for artifacts uploaded since SHA-256 support was added to the
 agent.
 

pages/agent/v3/help/_artifact_upload.md

@@ -32,42 +32,56 @@ Buildkite-managed Amazon S3 bucket, where they’re retained for six months.
 
 ### Example
 
-    $ buildkite-agent artifact upload "log/**/*.log"
+```shell
+$ buildkite-agent artifact upload "log/**/*.log"
+```
 
 You can also upload directly to Amazon S3 if you'd like to host your own artifacts:
 
-    $ export BUILDKITE_S3_ACCESS_KEY_ID=xxx
-    $ export BUILDKITE_S3_SECRET_ACCESS_KEY=yyy
-    $ export BUILDKITE_S3_DEFAULT_REGION=eu-central-1 # default is us-east-1
-    $ export BUILDKITE_S3_ACL=private # default is public-read
-    $ buildkite-agent artifact upload "log/**/*.log" s3://name-of-your-s3-bucket/$BUILDKITE_JOB_ID
+```shell
+$ export BUILDKITE_S3_ACCESS_KEY_ID=xxx
+$ export BUILDKITE_S3_SECRET_ACCESS_KEY=yyy
+$ export BUILDKITE_S3_DEFAULT_REGION=eu-central-1 # default is us-east-1
+$ export BUILDKITE_S3_ACL=private # default is public-read
+$ buildkite-agent artifact upload "log/**/*.log" s3://name-of-your-s3-bucket/$BUILDKITE_JOB_ID
+```
 
 You can use Amazon IAM assumed roles by specifying the session token:
 
-    $ export BUILDKITE_S3_SESSION_TOKEN=zzz
+```shell
+$ export BUILDKITE_S3_SESSION_TOKEN=zzz
+```
 
 Or upload directly to Google Cloud Storage:
 
-    $ export BUILDKITE_GS_ACL=private
-    $ buildkite-agent artifact upload "log/**/*.log" gs://name-of-your-gs-bucket/$BUILDKITE_JOB_ID
+```shell
+$ export BUILDKITE_GS_ACL=private
+$ buildkite-agent artifact upload "log/**/*.log" gs://name-of-your-gs-bucket/$BUILDKITE_JOB_ID
+```
 
 Or upload directly to Artifactory:
 
-    $ export BUILDKITE_ARTIFACTORY_URL=http://my-artifactory-instance.com/artifactory
-    $ export BUILDKITE_ARTIFACTORY_USER=carol-danvers
-    $ export BUILDKITE_ARTIFACTORY_PASSWORD=xxx
-    $ buildkite-agent artifact upload "log/**/*.log" rt://name-of-your-artifactory-repo/$BUILDKITE_JOB_ID
+```shell
+$ export BUILDKITE_ARTIFACTORY_URL=http://my-artifactory-instance.com/artifactory
+$ export BUILDKITE_ARTIFACTORY_USER=carol-danvers
+$ export BUILDKITE_ARTIFACTORY_PASSWORD=xxx
+$ buildkite-agent artifact upload "log/**/*.log" rt://name-of-your-artifactory-repo/$BUILDKITE_JOB_ID
+```
 
-By default, symlinks to directories will not be explored when resolving the glob, but symlinks to files will be uploaded as the linked files.
-To ignore symlinks to files use:
+By default, symlinks to directories will not be explored when resolving the glob, but symlinks to
+files will be uploaded as the linked files. To ignore symlinks to files use:
 
-    $ buildkite-agent artifact upload --upload-skip-symlinks "log/**/*.log"
+```shell
+$ buildkite-agent artifact upload --upload-skip-symlinks "log/**/*.log"
+```
 
 Note: uploading symlinks to files without following them is not supported.
 If you need to preserve them in a directory, we recommend creating a tar archive:
 
-    $ tar -cvf log.tar log/**/*
-    $ buildkite-agent upload log.tar
+```shell
+$ tar -cvf log.tar log/**/*
+$ buildkite-agent upload log.tar
+```
 
 ### Options
 

pages/agent/v3/help/_bootstrap.md

@@ -34,9 +34,13 @@ See https://buildkite.com/docs/agent/v3/hooks for more details.
 
 ### Example
 
-    $ eval $(curl -s -H "Authorization: Bearer xxx" \
-        "https://api.buildkite.com/v2/organizations/[org]/pipelines/[proj]/builds/[build]/jobs/[job]/env.txt" | sed 's/^/export /')
-    $ buildkite-agent bootstrap --build-path builds
+```shell
+$ eval $(curl -s -H "Authorization: Bearer xxx" \
+   "https://api.buildkite.com/v2/organizations/[org]/pipelines/[proj]/builds/[build]/jobs/[job]/env.txt" | \
+   sed 's/^/export /' \
+ )
+$ buildkite-agent bootstrap --build-path builds
+```
 
 ### Options
 

pages/agent/v3/help/_env_dump.md

@@ -17,6 +17,7 @@ script.
 `buildkite-agent env dump [options]`
 
 ### Description
+
 Prints out the environment of the current process as a JSON object, easily
 parsable by other programs. Used when executing hooks to discover changes
 that hooks make to the environment.

pages/agent/v3/help/_env_get.md

@@ -17,6 +17,7 @@ script.
 `buildkite-agent env get [variables]`
 
 ### Description
+
 Retrieves environment variables and their current values from the current job
 execution environment.
 
@@ -28,6 +29,7 @@ phases of the job. However, `env get` can be used to inspect the changes made
 with `env set` and `env unset`.
 
 ### Examples
+
 Getting all variables in key=value format:
 
 ```shell

pages/agent/v3/help/_env_set.md

@@ -17,6 +17,7 @@ script.
 `buildkite-agent env set [variable]`
 
 ### Description
+
 Sets environment variables in the current job execution environment.
 Changes to the job environment variables only apply to subsequent phases of the job.
 This command cannot unset Buildkite read-only variables.