a real start to a command reference

iterative · Nov 30, 2021 · 3046c16 · 3046c16
1 parent da00a13
commit 3046c16
Show file tree

Hide file tree

Showing 7 changed files with 84 additions and 103 deletions.
diff --git a/content/docs/ref/index.md b/content/docs/ref/index.md
@@ -4,14 +4,13 @@
 
 All CML commands support the following options:
 
-- `--driver=<ci>`: CI provider where the repository is hosted, choices: {github,
-  gitlab, bitbucket} [default: *inferred from environment*].
-- `--repo=<repo or org>`: Repository (or Organization) to be used [default:
-  *inferred from environment*].
-- `--token=<PAT>`:
+- `--driver={github,gitlab,bitbucket}`: CI provider where the repository is
+  hosted [default: *inferred from environment*].
+- `--repo=<...>`: Repository (or Organization) to be used [default: *inferred
+  from environment*].
+- `--token=<...>`:
   [Personal/project access token](https://cml.dev/doc/self-hosted-runners#personal-access-token)
   to be used [default: *inferred from environment*].
+- `--log={error,warn,info,debug}`: Maximum log level [default: `info`].
 - `--help`: Show help.
-- `--log=<level>`: Maximum log level, choices: {error, warn, info, debug}
-  [default: info].
 - `--version`: Show version number.
diff --git a/content/docs/ref/pr.md b/content/docs/ref/pr.md
@@ -17,12 +17,11 @@ preventing an infinite chain of runs.
 
 Any [generic option](/doc/ref) in addition to:
 
-```
---md          Output in markdown format [](url).                     [boolean]
---remote      Sets git remote.                    [string] [default: "origin"]
---user-email  Sets git user email.   [string] [default: "[email protected]"]
---user-name   Sets git user name.            [string] [default: "Olivaw[bot]"]
-```
+- `--md`: Produce output in markdown format (`[](url)`).
+- `--remote=<...>`: Git remote name or URL [default: `origin`].
+- `--user-email=<...>`: Git user email for commits [default:
+  `[email protected]`].
+- `--user-name=<...>`: Git user name for commits [default: `Olivaw[bot]`].
 
 ## Examples
 

diff --git a/content/docs/ref/publish.md b/content/docs/ref/publish.md
@@ -10,20 +10,18 @@ Publicly host an image for displaying in a CML report.
 
 Any [generic option](/doc/ref) in addition to:
 
-```
-    --md                        Output in markdown format [title ||
-                                name](url).                          [boolean]
--t, --title                     Markdown title [title](url) or ![](url title).
-                                                                      [string]
-    --native, --gitlab-uploads  Uses driver's native capabilities to upload
-                                assets instead of CML's storage. Currently
-                                only available for GitLab CI.        [boolean]
-    --rm-watermark              Avoid CML watermark.                 [boolean]
-    --mime-type                 Specifies the mime-type. If not set guess it
-                                from the content.                     [string]
--f, --file                      Append the output to the given file. Create it
-                                if does not exist.                    [string]
-```
+- `--md`: Produce output in markdown format.
+- `-t=<...>`, `--title=<...>`: Title for markdown output.
+- `-f=<...>`, `--file=<...>`: Append output to the given file instead of
+  `stdout`.
+- `--mime-type=<...>`: Content
+  [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml)
+  [default: *inferred from content*].
+- `--native`, `--gitlab-uploads`: Uses CI provider's native storage instead of
+  CML's. Currently
+  [only available for GitLab CI](https://github.com/iterative/cml/wiki/Backend-Supported-Features).
+- `--rm-watermark`: Don't inject a watermark into the comment. Will break some
+  CML functionality which needs to distinguish CML reports from other comments.
 
 ## Examples
 

diff --git a/content/docs/ref/runner.md b/content/docs/ref/runner.md
@@ -11,46 +11,38 @@ compute provider or locally on-premise).
 
 Any [generic option](/doc/ref) in addition to:
 
-```
---labels                    One or more user-defined labels for this runner
-                            (delimited with commas)  [string] [default: "cml"]
---idle-timeout              Seconds to wait for jobs before shutting down. Set
-                            to -1 to disable timeout   [number] [default: 300]
---name                      Name displayed in the repository once registered
-                                                  [string] [default: cml-{ID}]
---no-retry                  Do not restart workflow terminated due to instance
-                            disposal or GitHub Actions timeout       [boolean]
---single                    Exit after running a single job          [boolean]
---reuse                     Don't launch a new runner if an existing one has
-                            the same name or overlapping labels      [boolean]
---cloud                     Cloud to deploy the runner
-                       [string] [choices: "aws", "azure", "gcp", "kubernetes"]
---cloud-region              Region where the instance is deployed. Choices:
-                            [us-east, us-west, eu-west, eu-north]. Also
-                            accepts native cloud regions
-                                                 [string] [default: "us-west"]
---cloud-type                Instance type. Choices: [m, l, xl]. Also supports
-                            native types like i.e. t2.micro           [string]
---cloud-permission-set      Specifies the instance profile in AWS or instance
-                            service account in GCP      [string] [default: ""]
---cloud-metadata            Key Value pairs to associate cml-runner instance
-                            on the provider i.e. tags/labels "key=value"
-                                                         [array] [default: []]
---cloud-gpu                 GPU type.
-                           [string] [choices: "nogpu", "k80", "v100", "tesla"]
---cloud-hdd-size            HDD size in GB                            [number]
---cloud-ssh-private         Custom private RSA SSH key. If not provided an
-                            automatically generated throwaway key will be used
-                                                                      [string]
---cloud-spot                Request a spot instance                  [boolean]
---cloud-spot-price          Maximum spot instance bidding price in USD.
-                            Defaults to the current spot bidding price
-                                                        [number] [default: -1]
---cloud-startup-script      Run the provided Base64-encoded Linux shell script
-                            during the instance initialization        [string]
---cloud-aws-security-group  Specifies the security group in AWS
-                                                        [string] [default: ""]
-```
+- `--labels=<...>`: One or more (comma-delimited) labels for this runner
+  [default: `cml`].
+- `--name=<...>`: Runner name displayed in the CI [default: `cml-{ID}`].
+- `--idle-timeout=<...>`: Seconds to wait for jobs before shutting down. Set to
+  `-1` to disable timeout [default: `300`].
+- `--no-retry`: Don't restart the workflow when terminated due to instance
+  disposal or
+  [GitHub Actions timeout](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners#usage-limits).
+- `--single`: Shutdown runner after one workflow run.
+- `--reuse`: Don't launch a new runner if an existing one has the same name or
+  overlapping labels.
+- `--cloud={aws,azure,gcp,kubernetes}`: Cloud compute provider to host the
+  runner.
+- `--cloud-region={us-east,us-west,eu-west,eu-north,...}`: Region where the
+  instance is deployed. Also accepts native cloud regions [default: `us-west`].
+- `--cloud-type={m,l,xl,...}`: Instance type. Also accepts native types such as
+  `t2.micro`.
+- `--cloud-permission-set=<...>`: AWS instance profile or GCP instance service
+  account.
+- `--cloud-metadata=<...>`: `key=value` pair to associate with cloud runner
+  instances. May be [specified multiple times](http://yargs.js.org/docs/#array).
+- `--cloud-gpu={nogpu,k80,v100,tesla}`: GPU type.
+- `--cloud-hdd-size=<...>`: Disk storage size in GB.
+- `--cloud-ssh-private=<...>`: Private SSH RSA key [default: *auto-generate
+  throwaway key*].
+- `--cloud-spot`: Request a preemptible spot instance.
+- `--cloud-spot-price=<...>`: Maximum spot instance USD bidding price, [default:
+  *current price*].
+- `--cloud-startup-script=<...>`: Run the provided
+  [Base64](https://linux.die.net/man/1/base64)-encoded Linux shell script during
+  the instance initialization.
+- `--cloud-aws-security-group=<...>`: AWS security group.
 
 ## FAQs and Known Issues
 

diff --git a/content/docs/ref/send-comment.md b/content/docs/ref/send-comment.md
@@ -16,17 +16,15 @@ comments to the new PR if desired.
 
 Any [generic option](/doc/ref) in addition to:
 
-```
---pr                      Post to an existing PR/MR associated with the
-                          specified commit                           [boolean]
---commit-sha, --head-sha  Commit SHA linked to this comment. Defaults to HEAD.
-                                                                      [string]
---update                  Update the last CML comment (if any) instead of
-                          creating a new one                         [boolean]
---rm-watermark            Avoid watermark. CML needs a watermark to be able to
-                          distinguish CML reports from other comments in order
-                          to provide extra functionality.            [boolean]
-```
+- `--commit-sha=<...>`, `--head-sha=<...>`:
+  [Git revision](https://git-scm.com/docs/gitrevisions) linked to this comment
+  [default: `HEAD`].
+- `--pr`: Post to an existing PR/MR associated with the specified commit.
+- `--update`: Update the last CML comment (if any) instead of creating a new
+  one.
+- `--rm-watermark`: Don't inject a watermark into the comment. Will break some
+  CML functionality (such as `--update`) which needs to distinguish CML reports
+  from other comments.
 
 ## FAQs and Known Issues
 

diff --git a/content/docs/ref/send-github-check.md b/content/docs/ref/send-github-check.md
@@ -11,12 +11,9 @@ Similar to [`send-comment`](/doc/ref/send-comment), but using GitHub's
 
 Any [generic option](/doc/ref) in addition to:
 
-```
---commit-sha, --head-sha  Commit SHA linked to this comment. Defaults to HEAD.
-                                                                      [string]
---conclusion              Sets the conclusion status of the check.
-   [string] [choices: "success", "failure", "neutral", "cancelled", "skipped",
-                                             "timed_out"] [default: "success"]
---title                   Sets title of the check.
-                                              [string] [default: "CML Report"]
-```
+- `--commit-sha=<...>`, `--head-sha=<...>`:
+  [Git revision](https://git-scm.com/docs/gitrevisions) linked to this check
+  [default: `HEAD`].
+- `--title=<...>`: The check's title [default: `CML Report`].
+- `--conclusion={success,failure,neutral,cancelled,skipped,timed_out}`: The
+  check's status [default: `success`].
diff --git a/content/docs/ref/tensorboard-dev.md b/content/docs/ref/tensorboard-dev.md
@@ -10,22 +10,20 @@ Return a link to a <https://tensorboard.dev> page.
 
 Any [generic option](/doc/ref) in addition to:
 
-```
--c, --credentials   TB credentials as json. Usually found at
-                    ~/.config/tensorboard/credentials/uploader-creds.json. If
-                    not specified will look for the json at the env variable
-                    TB_CREDENTIALS.                        [string] [required]
-    --logdir        Directory containing the logs to process.         [string]
-    --name          Tensorboard experiment title. Max 100 characters. [string]
-    --description   Tensorboard experiment description. Markdown format. Max
-                    600 characters.                                   [string]
-    --md            Output as markdown [title || name](url).         [boolean]
--t, --title         Markdown title, if not specified, param name will be used.
-                                                                      [string]
--f, --file          Append the output to the given file. Create it if does not
-                    exist.                                            [string]
-    --rm-watermark  Avoid CML watermark.                             [boolean]
-```
+- `-c=<...>`, `--credentials=<...>`: TensorBoard JSON credentials (usually found
+  at `~/.config/tensorboard/credentials/uploader-creds.json`) [default:
+  *inferred from environment `TB_CREDENTIALS`*].
+- `--logdir=<...>`: Directory containing the logs to process.
+- `--name=<...>`: TensorBoard experiment title (up to 100 characters).
+- `--description=<...>`: TensorBoard experiment description (markdown format, up
+  to 600 characters).
+- `--md`: Produce output in markdown format (`[title](url)`).
+- `-t=<...>`, `--title=<...>`: Title for markdown output [default: *value of
+  `--name`*].
+- `-f=<...>`, `--file=<...>`: Append output to the given file instead of
+  `stdout`.
+- `--rm-watermark`: Don't inject a watermark into the comment. Will break some
+  CML functionality which needs to distinguish CML reports from other comments.
 
 ## Examples