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..e33ef178 100644 --- a/content/docs/ref/index.md +++ b/content/docs/ref/index.md @@ -1,5 +1,18 @@ # Command Reference +CML provides a number of commands to help package the outputs of ML workflows +into a CML report, which may include numeric data or model performance +visualizations. Let's look at the typical sequence (after +[configuration](/doc/user-guide)): + +∞ `cml runner` launches a runner hosted by a cloud compute provider or +[on-premise](/doc/self-hosted-runners). + +∞ `cml pr` commits a set of files to a new branch and create a pull request. + +∞ `cml comment` posts a Markdown report as a comment on a commit or pull/merge +request. + ## Generic Options All CML commands support the following options: diff --git a/content/docs/sidebar.json b/content/docs/sidebar.json index 192371d4..f01f8967 100644 --- a/content/docs/sidebar.json +++ b/content/docs/sidebar.json @@ -24,14 +24,19 @@ } ] }, - "usage", { - "label": "CML with DVC", - "slug": "cml-with-dvc" - }, - { - "label": "Self-hosted Runners", - "slug": "self-hosted-runners" + "slug": "user-guide", + "source": "user-guide/index.md", + "children": [ + { + "label": "CML with DVC", + "slug": "cml-with-dvc" + }, + { + "label": "Self-hosted Runners", + "slug": "self-hosted-runners" + } + ] }, { "label": "Command Reference", diff --git a/content/docs/cml-with-dvc.md b/content/docs/user-guide/cml-with-dvc.md similarity index 100% rename from content/docs/cml-with-dvc.md rename to content/docs/user-guide/cml-with-dvc.md diff --git a/content/docs/usage.md b/content/docs/user-guide/index.md similarity index 60% rename from content/docs/usage.md rename to content/docs/user-guide/index.md index 38863748..83d16fef 100644 --- a/content/docs/usage.md +++ b/content/docs/user-guide/index.md @@ -1,4 +1,4 @@ -# Using CML +# User Guide: Introduction A GitLab, GitHub, or Bitbucket account is required. Familiarity with [GitHub Actions](https://help.github.com/en/actions), @@ -9,7 +9,9 @@ also be beneficial. -The key file in any CML project is `.github/workflows/cml.yaml`: +Integrate CML to your +[workflow configuration](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) +using a `.github/workflows/cml.yaml` file, for example: ```yaml name: CML @@ -44,8 +46,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 +69,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 +90,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 +121,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,19 +143,31 @@ 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) + + +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 + + +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 + + +### Example project - [Basic CML project](https://bitbucket.org/iterative-ai/cml-base-case) - [CML with DVC to pull data](https://bitbucket.org/iterative-ai/cml-dvc-case) @@ -149,59 +176,3 @@ 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. - -∞ **[`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))\ -e.g. `cml runner launch --cloud={aws,azure,gcp,kubernetes} ...` - -∞ **[`pr`](/doc/ref/pr)**\ -Commit specified files to a new branch and create a pull request\ -e.g. `cml pr create "**/*.json" "**/*.py" --md >> report.md` - -∞ **[`comment`](/doc/ref/comment)**\ -Post a Markdown report as a commit comment\ -e.g. `cml comment create report.md` - -∞ **[`check`](/doc/ref/check)**\ -Post a Markdown report as a GitHub check\ -e.g. `cml check create report.md` - -∞ **[`tensorboard`](/doc/ref/tensorboard)**\ -Return a link to a page\ -e.g. `cml tensorboard connect --logdir=./logs --md >> report.md` - -### CML Reports - -The `cml comment create` command can be used to post reports. CML reports are -written in Markdown ([GitHub](https://github.github.com/gfm), -[GitLab](https://docs.gitlab.com/ee/user/markdown.html), or -[Bitbucket](https://confluence.atlassian.com/bitbucketserver/markdown-syntax-guide-776639995.html) -flavors). That means they can contain images, tables, formatted text, HTML -blocks, code snippets and more — really, what you put in a CML report is up to -you. Some examples: - -📝 **Text** Write to your report using whatever method you prefer. For example, -copy the contents of a text file containing the results of ML model training: - -```cli -$ cat results.txt >> report.md -``` - -🖼️ **Images** Display images using the markdown or HTML. Note that if an image -is an output of your ML workflow (i.e. it is produced by your workflow), you can -use markdown to embed it in a CML report. For example, if `plot.png` is output -by `python train.py`, run: - -```cli -$ echo '![](./plot.png)' >> report.md -$ cml comment create report.md -``` diff --git a/content/docs/self-hosted-runners.md b/content/docs/user-guide/self-hosted-runners.md similarity index 100% rename from content/docs/self-hosted-runners.md rename to content/docs/user-guide/self-hosted-runners.md diff --git a/redirects-list.json b/redirects-list.json index 2d7a129e..f469acc2 100644 --- a/redirects-list.json +++ b/redirects-list.json @@ -6,11 +6,15 @@ "^/doc/start/start-github(/.*)?$ /doc/start/github", "^/doc/start/start-gitlab(/.*)?$ /doc/start/gitlab", - "^/doc/ref/send-github-check(/.*)?$ /doc/ref/check$1 301", - "^/doc/ref/send-comment(/.*)?$ /doc/ref/comment$1 301", - "^/doc/ref/tensorboard-dev(/.*)?$ /doc/ref/tensorboard$1 301", + "^/doc/usage$ /doc/user-guide", + "^/doc/cml-with-dvc$ /doc/user-guide/cml-with-dvc 302", + "^/doc/self-hosted-runners$ /doc/user-guide/self-hosted-runners 302", - "^/doc/cml-with-npm(/.*)?$ /doc/install$1 301", + "^/doc/ref/send-github-check(/.*)?$ /doc/ref/check$1", + "^/doc/ref/send-comment(/.*)?$ /doc/ref/comment$1", + "^/doc/ref/tensorboard-dev(/.*)?$ /doc/ref/tensorboard$1", + + "^/doc/cml-with-npm(/.*)?$ /doc/install$1", "^/(.+)/$ /$1" ]