diff --git a/content/docs/ref/comment.md b/content/docs/ref/comment.md index 10e5ccb4..954b84d5 100644 --- a/content/docs/ref/comment.md +++ b/content/docs/ref/comment.md @@ -33,16 +33,21 @@ Any [generic option](/doc/ref) in addition to: (`pr`, `commit`, `issue`), optionally with a reference (`issue/12`, `pr/17`, `commit/`[rev](https://git-scm.com/docs/gitrevisions) [default: `pr` falling back to `commit/HEAD`]. + - `--watch`: Watch for changes and automatically update the comment (doesn't exit, consider [appending `&` to run in the background]()). + - `--publish=`: Upload any local images found in the Markdown report [default: `true`]. + - `--publish-native`: Use `--driver`'s native capabilities to `--publish` assets instead of `--publish-url` (not available on `--driver=github`). + - `--publish-url=<...>`: Self-hosted image server URL [default: `https://asset.cml.dev`], see [minroud-s3](https://github.com/iterative/minroud-s3). + - `--watermark-title=<...>`: Hidden comment marker (useful to [specify which comment to update](#managing-multiple-comments) in subsequent `cml comment update` calls); `"{workflow}"` and `"{run}"` are auto-replaced. diff --git a/content/docs/ref/index.md b/content/docs/ref/index.md index 51e83752..daa6db23 100644 --- a/content/docs/ref/index.md +++ b/content/docs/ref/index.md @@ -1,5 +1,9 @@ # Command Reference +CML provides a number of commands to help package the outputs of ML workflows +(including numeric data and visualizations about model performance) into a CML +report. + ## Generic Options All CML commands support the following options: diff --git a/content/docs/usage.md b/content/docs/usage.md index 38863748..48b9f9ca 100644 --- a/content/docs/usage.md +++ b/content/docs/usage.md @@ -1,4 +1,4 @@ -# Using CML +# Usage A GitLab, GitHub, or Bitbucket account is required. Familiarity with [GitHub Actions](https://help.github.com/en/actions), @@ -44,8 +44,10 @@ jobs: cml comment create report.md ``` -The example above generates visual reports in pull requests: -[![](/img/cml_first_report.png)](https://github.com/iterative/cml_base_case/pull/2) +This generates visual reports in pull requests (see `cml comment create`): + +![First CML report in GitHub](/img/cml_first_report.png) _From sample +[increase forest depth](https://github.com/iterative/cml_base_case/pull/2) PR_ We helpfully provide CML and other useful libraries pre-installed on our [custom Docker images](/doc/self-hosted-runners#docker-images). In the above @@ -65,7 +67,9 @@ and CML set up on an Ubuntu LTS base for convenience. -The key file in any CML project is `.gitlab-ci.yml`: +Integrate CML to your +[pipeline configuration](https://docs.gitlab.com/ee/ci/pipelines/#configure-a-pipeline) +using the `.gitlab-ci.yml` file, for example: ```yaml train-model: @@ -84,12 +88,19 @@ create-CML-report: - cml comment create report.md ``` -⚠️ You _must_ provide a + + +You _must_ provide a [personal or project access token (PAT)](/doc/self-hosted-runners#personal-access-token) via a `REPO_TOKEN` variable. -The example above generates visual reports in merge requests: -[![](/img/GitLab_CML_report.png '=400')](https://gitlab.com/iterative.ai/cml-base-case/-/merge_requests/1) + + +This generates visual reports in pull requests (see `cml comment create`): + +![First CML report in GitLab](/img/GitLab_CML_report.png '=400') _From sample +[Experiment](https://gitlab.com/iterative.ai/cml-base-case/-/merge_requests/1) +MR_ We helpfully provide CML and other useful libraries pre-installed on our [custom Docker images](/doc/self-hosted-runners#docker-images). In the above @@ -108,7 +119,9 @@ set up on an Ubuntu LTS base for convenience. -The key file in any CML project is `bitbucket-pipelines.yml`: +Integrate CML to your +[pipeline configuration](https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/) +using the `bitbucket-pipelines.yml` file, for example: ```yaml image: iterativeai/cml:0-dvc2-base1 @@ -128,18 +141,30 @@ pipelines: - cml comment create report.md ``` -⚠️ You _must_ provide + + +You _must_ provide [access credentials](/doc/self-hosted-runners#personal-access-token) via a `REPO_TOKEN` variable. -The example above generates visual reports in pull requests: -[![](/img/bitbucket_cloud_pr.png '=600')](https://bitbucket.org/iterative-ai/cml-base-case/pull-requests/1) + -⚠️ CML works with Bitbucket Cloud, where you can use the +This generates visual reports in pull requests (see `cml comment create`): + +![First CML report in BitBucket](/img/bitbucket_cloud_pr.png '=600') _From +sample +[Experiment](https://bitbucket.org/iterative-ai/cml-base-case/pull-requests/1) +PR_ + + + +CML works with Bitbucket Cloud, where you can use the [Bitbucket Pipelines](https://bitbucket.org/product/features/pipelines) CI/CD system to run workflows automatically on triggering events. Bitbucket Server is not yet supported. + + ### Example projects - [Basic CML project](https://bitbucket.org/iterative-ai/cml-base-case) @@ -152,12 +177,8 @@ not yet supported. ## CML Commands -CML provides a number of commands to help package the outputs of ML workflows -(including numeric data and visualizations about model performance) into a CML -report. - -Below is a list of CML commands for starting cloud compute runners, writing and -publishing Markdown reports to your CI/CD system. +Below is a list of [CML commands](/doc/ref) for starting cloud compute runners, +writing and publishing Markdown reports to your CI/CD system. ∞ **[`runner`](/doc/ref/runner)**\ Launch a runner hosted by a cloud compute provider or locally on-premise (see [self-hosted runners](/doc/self-hosted-runners))\