Flesh out https://cml.dev/doc/contributing/core (follow-up to #73)

The helppage of cml-pr describes the option --token as a personal access token, but project access tokens can also be used for that. So i recommend to update the helppage by adding information about project access tokens.

• Draft Design Mockup
• Once design is completed, we need to update our header/footer to match design

I forgot to include the logos when optimizing screenshots, and the logo is huge!

It doesn't "remember" that state and breaks video player for me

This area will be updated as I figure out testing with these browsers, and what exactly is broken.

Depending on market share of incompatible browsers and the nature of required fixes, this could also be closed early. It's too soon to tell where it'll go.

Code examples not displaying escape \ chars at the end of long lines:

The paragraph under "CML Use Cases" uses thin-font and is on a very low contrast, which I'm finding very hard to read.

Or, is that the point?

• as per https://github.com/iterative/cml/#docker-images
• follow-up to #81

1. example repos
2. tutorial

• CML + DVC
  • self-hosted (GPU)
  • long-job
• CML + tensorboard: https://github.com/DavidGOrtega/fashion_mnist
  • without GPU (GHA runners)
  • without long-job (for now)

We are introducing cloud-permission-set in the next release.

• iterative/cml#781

Rather than writing separate pages for GH, GL and BB, it would in many cases be easier to write one page with a button to toggle between providers (similar to https://github.com/iterative/cml-website/blob/master/content/index.mdx but far simpler).

See e.g. https://zguide.zeromq.org/docs/chapter1/ for an example of clicking on a language next to code snippets to change the language of all snippets on the page (ofc we can do a lot better design-wise).

md interface options

html tags

# Installation

lorem ipsum...

<toggle>

<GitHub>

*bla bla* standard markdown...

```yml
- uses: iterative/setup-cml@v1
```

</GitHub>

<GitLab>

...

</GitLab>

<Bitbucket>

...

</Bitbucket>

</toggle>

tabbed

https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/

=== "GitHub"

    *bla bla* standard markdown...

    ```yml
    - uses: iterative/setup-cml@v1
    ```

=== "GitLab"

    ...

other ideas?

URL interface options

• cml.dev/doc/start?lang=gitlab#usage
• other ideas?

/CC @iterative/cml @julieg18 @rogermparent

This is the last of what looked to me like intricate components on the homepage (other than the hamburger menu)

Highlights look like this:

And on mouseover a tooltip should pop up with this design:

The implementation shouldn't interfere with code copying, either through mouse or the copy button.

None of the recent merged PRs are live (e.g. #89, #90, #91, #92 versus https://cml.dev/doc/self-hosted-runners)

E.g. it looks like favicon is too low res.

Some formats are not available according to https://realfavicongenerator.net/favicon_checker?protocol=http&site=cml.dev#.YWyLu9nMLlw (probably there are more websites like this).

We need to review all the regular fields one more time, make it a single source or truth. The same should be done to iterative.ai / dvc.org - they all should be using the same mechanism.

Just realized we are missing a social image on CML.dev. I can take care of it, but not sure where it lives and need appropriate sizing.
@casperdcl @rogermparent @julieg18

Discussed in iterative/dvc#6542

cml-cloud-set-up-cloud:
  name: CML (Cloud) - Set up cloud
  runs-on: ubuntu-20.04
  steps:
    - name: Cancel previous runs
      uses: styfle/[email protected]
      with:
        access_token: ${{ github.token }}
    - name: Checkout
      uses: actions/checkout@v2
    - name: Set up CML
      uses: iterative/setup-cml@v1
    - name: Set up cloud
      shell: bash
      env:
        REPO_TOKEN: ${{ secrets.CML_ACCESS_TOKEN }}
        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      run: |
        cml-runner \
        --cloud=aws \
        --cloud-region=us-west-2 \
        --cloud-type=t2.small \
        --labels=cml-runner
cml-cloud-train:
  name: CML (Cloud) - Train
  needs: cml-cloud-set-up-cloud
  runs-on: [self-hosted, cml-runner]
  # container: docker://iterativeai/cml:0-dvc2-base1-gpu
  container: docker://iterativeai/cml:0-dvc2-base1
  steps:
    - name: Cancel previous runs
      uses: styfle/[email protected]
      with:
        access_token: ${{ github.token }}
    - name: Checkout
      uses: actions/checkout@v2
    - name: Set up Miniconda
      uses: conda-incubator/setup-miniconda@v2
      with:
        miniconda-version: "latest"
        activate-environment: hm-cnn
    - name: Install requirements
      working-directory: convolutional-neural-network
      shell: bash -l {0}
      run: |
        conda install pytorch torchvision torchaudio --channel=pytorch
        conda install pandas
        conda install tabulate
        pip install -r requirements.txt
    - name: Pull Data
      working-directory: convolutional-neural-network
      env:
        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      run: |
        dvc pull
    - name: Train model
      working-directory: convolutional-neural-network
      shell: bash -l {0}
      env:
        WANDB_API_KEY: ${{ secrets.WANDB_API_KEY }}
      run: |
        dvc repro
    - name: Write CML report
      working-directory: convolutional-neural-network
      shell: bash -l {0}
      env:
        REPO_TOKEN: ${{ secrets.CML_ACCESS_TOKEN }}
      run: |
        echo "# CML (Cloud) Report" >> report.md
        echo "## Params" >> report.md
        cat output/reports/params.txt >> report.md
        cml-send-comment report.md

stages:
  prepare:
    cmd: tar -xf data/raw/cifar-10-python.tar.gz --dir=data/processed
    deps:
    - data/raw/cifar-10-python.tar.gz
    outs:
    - data/processed/cifar-10-batches-py/
  main:
    cmd: python main.py
    deps:
    - data/processed/cifar-10-batches-py/
    - evaluate.py
    - main.py
    - model/
    - train.py
    params:
    - lr
    - train.epochs
    outs:
    - output/models/model.pt

    - name: Train model
      working-directory: convolutional-neural-network
      shell: bash -l {0}
      env:
        WANDB_API_KEY: ${{ secrets.WANDB_API_KEY }}
      run: |
        dvc repro
        dvc push  # New added
        git add .  # New added
        git commit -m "update dvc.lock, etc."  # New added
        git push origin current_pr  # New added, need somehow get the current pull request name

There are a number of issues with the https://cml.dev banner

1. "Install" should be replaced with "Get Started" linking to https://cml.dev/doc/start
   • no popup (npm installation is not at all used in GitHub since we have https://github.com/iterative/setup-cml)

1. "Install" popup "More in documentation" links to non-existent https://github.com/iterative/cml#install-cml-as-a-package (can the link checker look for #ids?) Should be https://github.com/iterative/cml#local-package or https://cml.dev/doc/cml-with-npm
2. the word "GitHub" should be replaced with "Source" or simply a GH icon as per https://dvc.org
3. probably also add discord chat icon

Also "Download" button on landing page should be updated as per (1) above.

Example:

"engines": {
    "node": "14.x"
  }

Follow-up of #86 (comment) and #99 (comment)

I wonder if we should extract the container image documentation to a separate section, instead of keeping it inside the self-hosted runners section. Images are being used in many other scenarios, like running any CML command on CI/CD systems other than GitHub Actions.

• Currently all of our social images are using the old CML logo. We need to update all the images to have the new logo.

use tabs where appropriate

follow-up to #113 <- #70

<toggle>
<tab title="GitHub">
foo bar
</tab>
<tab title="GitLab">
baz bat
</tab>
</toggle>

Regarding the legal requirements, there must be a section on the website with a description of how to download and/or install the software.

Suggesting to add:

• A ghost 'install' button in the header on the top right. A click will show a simple flyout dialog. It closes after clicking everywhere outside the menu or after pressing the 'OK' button. The command copy button would be very useful here.
  

• A button 'Download' in the Hero section. It should redirect to the 'https://github.com/iterative/cml#install-cml-as-a-package' page with an anchor, as well as link 'More in documentation' in the popover.

Design mockups → Open in Figma.

Full mockup example

With the new educational course coming out at the end of the quarter, we need to determine how people will access it from our websites.

Each website will access the same school: Iterative Tools School.

Here is information on how their domains work. Let me know how you think it's best to proceed!

@julieg18 @rogermparent @yalozhkin

• video.play() and video.pause() return a promise and we should place our code in something like a try and catch block. Not doing so may be causing some errors that were caught by Sentry
• We could also use a catch block to take care of other Sentry video errors that we don't need to worry about

Links about issue

• Info about video.play()
• Google Developers article about errors

Sentry errors that could be resolved

• CML-DEV-5
• CML-DEV-C

This issue is exactly what it says on the tin. I'll update this as I get an understanding of pre-commit hooks and what makes sense to port over.

Refers to 1. CML contribs as well as 2. cml.dev/doc contribs.

• check dvc.org/doc guides for compatibility
• also check cml wiki for special info
• fix any issues
• add cml.dev/doc nav entry redirecting to dvc.org/doc guide

Implementation request for website team (if you're from CML or Documentation teams and want to discuss specifics please see #55 instead).

• Can we have a new doc subdomain & page (the "Doc(s)" link in the hero/header should go to https://doc.cml.dev which should have a similar layout to https://dvc.org/doc)
• In addition, we need subpages. All pages should have a ToC with a nested folder structure corresponding to layout in the cml-website repo.

Blank pages corresponding to folders:

• doc.cml.dev/ CML Documentation
  • /start/ Getting Started
    • /start/github/ Getting Started with GitHub <-- sub-page
  • /ref/ Command Reference
    • /ref/#send-comment cml-send-comment <-- in-page <h2>s which show up in the ToC
    • ... etc ...

Each page can be blank for now (I'll fill in content) 🙏 @rogermparent @julieg18

• dvc.org has had multiple updates that cml.dev's docs engine should have as well
  List of website updates:

• Lint all files
• Add image processing to docs images
• Update Link Check to 0.8
• Update docs hamburger menu

List of doc updates:

• replace cml-action => setup-cml
• fix missing redirect
• explicitly mark step

It is needed for trademark application

• our current favicon is currently using our old logo
  

This issue is meant to be a hub for discussion about pre-launch preparations for the cml.dev website. This issue should close just before the site goes public.

Sorted roughly in order of priority:

• Highlighted text (tooltips part 1) #2 #3
• Add final examples with tooltips in the right places (I think? may or may not remove cloud case)
• SEO Part 1: Metadata and good Lighthouse scores #15
• SEO part 2: Small details and keyword analysis #17
• Make the final landing videos #9
• Improve the container element for the landing video #4
• Background image #10
• Add the DVC.org logo to the footer
• Add an action to the subscribe form #14
• Ensure we have the social icons we want #13
• Refine styles/sizes to be DRYer and fully match the Figma (Very close, working toward 100% if not there already)
• Tooltips on highlights #2 #3 (Feature complete, but may need design adjustments)
• Make a Readme for site contributors (A skeleton, currently)

Individual issues will be created and linked here. This umbrella issue is probably best used for discussion around discovering and adding new pre-release issues.

Apparently npm up && yarn format-all && yarn pretty-quick changes files in Codespaces (Node v14) but not locally (Node v14).

• reported at #81 (comment)

When I copy the yaml and past it in vi/Notes it creates additional spaces in every single line like:

name: train-my-model



on: [push]



jobs:

  run:

    runs-on: [ubuntu-latest]

    container: docker://dvcorg/cml-py3:latest

    steps:

      - uses: actions/checkout@v2

      - name: cml_run

        env:

          repo_token: ${{ secrets.GITHUB_TOKEN }}

        run: |

          pip3 install -r requirements.txt

          python train.py



          cat metrics.txt >> report.md

          cml-publish confusion_matrix.png --md >> report.md

          cml-send-comment report.md

Same as with dvc.org - it's important to have for two reasons:

• trust - when people see 2000+ stars they trust the project more
• more people will want to go to GH and be involved (including start it)

Migrate to Heroku.
Netlify doesn't support CF caching on top of it, obscures too many things, doesn't give any reasonable value on top of Heroku + CF.

• any input you type in receives a "No Results Found" output

• GitHub #275
• GitLab #275
• Bitbucket #267

In some cases, I need to configure special parameters for the git lab runner that is created by the CML runner. I also need to be able to set special options for running the container.
For example:

• git lab runner must have the parameter: privileged = true
  or
• docker container must be started with the option: --log-driver=fluentd --log-opt fluentd-address=XX.XX.XX.XX:24224

To downgrade the account we need to use CF to cache.

Given:

<!-- /some/page.md -->
<toggle>
<tab title="Foo">
</tab>
<tab title="Bar">

some text

### sub section

</tab>
</toggle>

Should be able to use:

• /some/page?tab=Bar (or /some/page#Bar?) to auto-open the appropriate tab (p1-important, #130)
  • /some/page/?tab=Bar#sub-section (or /some/page#Bar-sub-section?) to auto-open the tab and scroll to containing section (p2-nice-to-have)
• remember the ?tab=<arg> when navigating to a different page (p2-nice-to-have)

Other tasks:

• initial tabs implementation (#113)
  • update styling a little (#136, TODO: follow-up)

• blocking #122
• related #70

Proposal. Discussion for @iterative/cml & @iterative/docs:

• A new docs page at a subdomain (the "Docs" link in the cml.dev hero/header should go to https://doc(s).cml.dev which should have a similar layout to https://dvc.org/doc).
• In addition, we need subpages. All pages should have a ToC.

Proposed layout:

• doc(s).cml.dev/ CML Documentation
  • /features/ Features
  • /start/ Getting Started
    • /start/github/ Getting Started with GitHub
    • /start/gitlab/ Getting Started with GitLab
  • /guide/ User Guide
  • /ref/ Command Reference
    • /ref/#pr cml-pr
    • /ref/#send-comment cml-send-comment
    • /ref/#tensorboard-dev cml-tensorboard-dev
    • ... etc ...

Currently this is what our 404 page looks like:

Currently we have a single description (summary about cml) for all pages. It would be better if we updated the descriptions depending on the docs page.

Possible option

• Write a description for each doc index page and update any pages inside of it accordingly. For example, write a description for our "Get Started" section and give that description to the /start, /start/github, and /start/gitlab.

• There are a couple ways we could do this. Two possibilities are using plausible analytics or have our backend handle analytics.