Usage: add GitLab, Bitbucket sections

content/docs/ref/pr.md

@@ -43,4 +43,5 @@ else
 fi
 ```
 
-Note: pull requests created with `cml pr` **won't** trigger a new CI/CD run under any circumstances.
+Note: pull requests created with `cml pr` **won't** trigger a new CI/CD run
+under any circumstances.

content/docs/self-hosted-runners.md

@@ -238,12 +238,12 @@ Use either:
 For instance, to use a personal access token:
 
 1. Navigate to **User Settings** → **Access Tokens**
-   - in the "Name" field, type `repo_token`
+   - in the "Name" field, type `REPO_TOKEN`
    - select `api`, `read_repository` and `write_repository`
    - click "Create personal access token" and copy it
 2. In your GitLab project, navigate to **Settings** → **CI/CD**
    → **Variables** → **Add Variable**
-   - in the "Key" field, type `repo_token`
+   - in the "Key" field, type `REPO_TOKEN`
    - in the "Value" field, paste your Personal Access Token
    - select "Mask variable"
    - deselect "Protect variable"
@@ -255,7 +255,7 @@ credentials.
 </tab>
 <tab title="Bitbucket">
 
-Bitbucket Cloud does not use access tokens. Instead, create a `repo_token`
+Bitbucket Cloud does not use access tokens. Instead, create a `REPO_TOKEN`
 variable with a Base64 encoded username and password.
 
 Use either:
@@ -268,15 +268,15 @@ Use either:
   intended use case: you limit the account to only access the repositories where
   you plan to deploy runners to.
 
-In either case, the steps to create a `repo_token` are:
+In either case, the steps to create a `REPO_TOKEN` are:
 
 1. Use a Base64 encoder of your choice to encode a Bitbucket username and
    password:
    - `echo $USERNAME:$PASSWORD | base64`
    - copy the resulting Base64 token
 2. In your repository, go to **Repository Settings** &rightarrow; **Repository
    Variables**
-   - in the "Name" field, type `repo_token`
+   - in the "Name" field, type `REPO_TOKEN`
    - in the "Value" field, paste the Base64 token
    - select `Secured` to hide credentials in all Bitbucket logs
 

content/docs/start/gitlab.md

@@ -61,16 +61,15 @@ Here, we'll walk through a tutorial to start using CML on GitLab.
    into a new file `.gitlab-ci.yml` and save.
 
    ```yaml
-   stages:
-     - cml_run
-
-   cml:
-     stage: cml_run
+   train-model:
      image: iterativeai/cml:0-dvc2-base1
      script:
-       - pip3 install -r requirements.txt
+       - pip install -r requirements.txt
        - python train.py
-
+   create-cml-report:
+     needs: train-model
+     image: iterativeai/cml:0-dvc2-base1
+     script:
        - cat metrics.txt >> report.md
        - cml publish confusion_matrix.png --md >> report.md
        - cml send-comment report.md

content/docs/start/index.md

@@ -34,12 +34,3 @@ _Need help? Just want to chat about continuous integration for ML?
 for hands-on MLOps tutorials using CML! 🌟
 
 https://youtu.be/9BgIDqAzfuA
-
-## Case studies
-
-Here are some example projects using CML.
-
-- [Basic CML project](https://github.com/iterative/cml_base_case)
-- [CML with DVC to pull data](https://github.com/iterative/cml_dvc_case)
-- [CML with Tensorboard](https://github.com/iterative/cml_tensorboard_case)
-- [CML with EC2 GPU](https://github.com/iterative/cml_cloud_case)

content/docs/usage.md

@@ -5,21 +5,8 @@ A GitLab, GitHub, or Bitbucket account is required. Familiarity with
 [GitLab CI/CD](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration)
 may also be beneficial.
 
-## GitLab
-
-Please see our docs on
-[CML with GitLab CI/CD](https://github.com/iterative/cml/wiki/CML-with-GitLab)
-and in particular the
-[personal access token](https://github.com/iterative/cml/wiki/CML-with-GitLab#variables)
-requirement.
-
-## Bitbucket
-
-Please see our docs on
-[CML with Bitbucket Cloud](https://github.com/iterative/cml/wiki/CML-with-Bitbucket-Cloud).
-_Bitbucket Server support estimated to arrive by mid 2021._
-
-## GitHub
+<toggle>
+<tab title="GitHub">
 
 The key file in any CML project is `.github/workflows/cml.yaml`:
 
@@ -36,7 +23,7 @@ jobs:
       # may need to setup Node.js & Python3 on e.g. self-hosted
       # - uses: actions/setup-node@v2
       #   with:
-      #     node-version: '12'
+      #     node-version: '14'
       # - uses: actions/setup-python@v2
       #   with:
       #     python-version: '3.x'
@@ -55,13 +42,106 @@ jobs:
           cml send-comment 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)
+
 We helpfully provide CML and other useful libraries pre-installed on our
 [custom Docker images](/doc/self-hosted-runners#docker-images). In the above
 example, uncommenting the
 `container: docker://ghcr.io/iterative/cml:0-dvc2-base1` field will make the
 runner pull the CML Docker image. The image already has Node.js, Python 3, DVC
 and CML set up on an Ubuntu LTS base for convenience.
 
+### Example projects
+
+- [Basic CML project](https://github.com/iterative/cml_base_case)
+- [CML with DVC to pull data](https://github.com/iterative/cml_dvc_case)
+- [CML with Tensorboard](https://github.com/iterative/cml_tensorboard_case)
+- [CML with EC2 GPU](https://github.com/iterative/cml_cloud_case)
+
+</tab>
+<tab title="GitLab">
+
+The key file in any CML project is `.gitlab-ci.yml`:
+
+```yml
+train-model:
+  # use a convenient Ubuntu LTS + DVC + CML container
+  image: iterativeai/cml:0-dvc2-base1
+  script:
+    - pip install -r requirements.txt
+    - python train.py
+create-CML-report:
+  needs: train-model
+  image: iterativeai/cml:0-dvc2-base1
+  script:
+    - cat metrics.txt >> report.md
+    - cml publish confusion_matrix.png --md >> report.md
+    - cml send-comment report.md
+```
+
+⚠️ 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/3)
+
+We helpfully provide CML and other useful libraries pre-installed on our
+[custom Docker images](/doc/self-hosted-runners#docker-images). In the above
+example, the `image: iterativeai/cml:0-dvc2-base1` field will make the runner
+pull the CML Docker image. The image already has Node.js, Python 3, DVC and CML
+set up on an Ubuntu LTS base for convenience.
+
+### Example projects
+
+- [Basic CML project](https://gitlab.com/iterative.ai/cml-base-case)
+- [CML with DVC to pull data](https://gitlab.com/iterative.ai/cml-dvc-case)
+- [CML with Tensorboard](https://gitlab.com/iterative.ai/cml-tensorboard-case)
+- [CML with EC2 GPU](https://gitlab.com/iterative.ai/cml-cloud-case)
+
+</tab>
+<tab title="Bitbucket">
+
+The key file in any CML project is `bitbucket-pipelines.yml`:
+
+```yaml
+image: iterativeai/cml:0-dvc2-base1
+pipelines:
+  default:
+    - step:
+        name: Train model
+        script:
+          - pip install -r requirements.txt
+          - python train.py
+    - step:
+        name: Create CML report
+        script:
+          - cat metrics.txt > report.md
+          - echo >> report.md
+          - cml publish confusion_matrix.png --md >> report.md
+          - cml send-comment report.md
+```
+
+⚠️ 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/2)
+
+⚠️ 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)
+
+</tab>
+</toggle>
+
 ## CML Commands
 
 CML provides a number of commands to help package the outputs of ML workflows