Provide Docs URLs in --help messaging (#1232)

* initial setup

* npm run do_snapshots

* now with a test

* Update bin/cml.test.js

bin/cml.test.js

@@ -1,4 +1,5 @@
 const { exec } = require('../src/utils');
+const fetch = require('node-fetch');
 
 describe('command-line interface tests', () => {
   test('cml --help', async () => {
@@ -31,3 +32,21 @@ describe('command-line interface tests', () => {
     `);
   });
 });
+
+describe('Valid Docs URLs', () => {
+  test.each([
+    'workflow/rerun',
+    'tensorboard/connect',
+    'runner/launch',
+    'repo/prepare',
+    'pr/create',
+    'comment/create',
+    'comment/update',
+    'check/create',
+    'asset/publish'
+  ])('Check Docs Link', async (cmd) => {
+    const { DOCSURL } = require(`./cml/${cmd}`);
+    const { status } = await fetch(DOCSURL);
+    expect(status).toBe(200);
+  });
+});

bin/cml/asset/publish.js

@@ -4,8 +4,11 @@ const winston = require('winston');
 
 const { CML } = require('../../../src/cml');
 
+const DESCRIPTION = 'Publish an asset';
+const DOCSURL = 'https://cml.dev/doc/usage#cml-reports';
+
 exports.command = 'publish <asset>';
-exports.description = 'Publish an asset';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   if (opts.gitlabUploads) {
@@ -76,3 +79,4 @@ exports.options = kebabcaseKeys({
       'Specifies the repo to be used. If not specified is extracted from the CI ENV.'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/check/create.js

@@ -1,8 +1,11 @@
 const fs = require('fs').promises;
 const kebabcaseKeys = require('kebabcase-keys');
 
+const DESCRIPTION = 'Create a check report';
+const DOCSURL = 'https://cml.dev/doc/ref/check';
+
 exports.command = 'create <markdown file>';
-exports.description = 'Create a check report';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { cml, markdownfile } = opts;
@@ -53,3 +56,4 @@ exports.options = kebabcaseKeys({
     description: 'Title of the check'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/comment/create.js

@@ -1,7 +1,10 @@
 const kebabcaseKeys = require('kebabcase-keys');
 
+const DESCRIPTION = 'Create a comment';
+const DOCSURL = 'https://cml.dev/doc/ref/comment#create';
+
 exports.command = 'create <markdown file>';
-exports.description = 'Create a comment';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { cml } = opts;
@@ -72,3 +75,4 @@ exports.options = kebabcaseKeys({
     telemetryData: 'name'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/comment/update.js

@@ -1,10 +1,14 @@
 const { builder, handler } = require('./create');
 
+const DESCRIPTION = 'Update a comment';
+const DOCSURL = 'https://cml.dev/doc/ref/comment#update';
+
 exports.command = 'update <markdown file>';
-exports.description = 'Update a comment';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   await handler({ ...opts, update: true });
 };
 
 exports.builder = builder;
+exports.DOCSURL = DOCSURL;

bin/cml/pr/create.e2e.test.js

@@ -12,6 +12,7 @@ describe('CML e2e', () => {
       Commands:
         cml.js pr create <glob path...>  Create a pull request with the specified
                                          files
+                                         https://cml.dev/doc/ref/pr
 
       Global Options:
         --log     Logging verbosity

bin/cml/pr/create.js

@@ -6,8 +6,11 @@ const {
   GIT_USER_EMAIL
 } = require('../../../src/cml');
 
+const DESCRIPTION = 'Create a pull request with the specified files';
+const DOCSURL = 'https://cml.dev/doc/ref/pr';
+
 exports.command = 'create <glob path...>';
-exports.description = 'Create a pull request with the specified files';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { cml, globpath: globs } = opts;
@@ -78,3 +81,4 @@ exports.options = kebabcaseKeys({
     description: 'Git user name'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/repo/prepare.js

@@ -2,8 +2,11 @@ const kebabcaseKeys = require('kebabcase-keys');
 
 const { GIT_USER_NAME, GIT_USER_EMAIL } = require('../../../src/cml');
 
+const DESCRIPTION = 'Prepare the cloned repository';
+const DOCSURL = 'https://cml.dev/doc/ref/ci';
+
 exports.command = 'prepare';
-exports.description = 'Prepare the cloned repository';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { cml } = opts;
@@ -33,3 +36,4 @@ exports.options = kebabcaseKeys({
     description: 'Git user name'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/runner/launch.js

@@ -404,8 +404,11 @@ const run = async (opts) => {
   else await runLocal(opts);
 };
 
+const DESCRIPTION = 'Launch and register a self-hosted runner';
+const DOCSURL = 'https://cml.dev/doc/ref/runner';
+
 exports.command = 'launch';
-exports.description = 'Launch and register a self-hosted runner';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   ({ cml } = opts);
@@ -579,3 +582,4 @@ exports.options = kebabcaseKeys({
       'Seconds to wait for collecting logs on failure (https://github.com/iterative/cml/issues/413)'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/runner/launch.test.js

@@ -11,6 +11,7 @@ describe('CML e2e', () => {
 
       Commands:
         cml.js runner launch  Launch and register a self-hosted runner
+                              https://cml.dev/doc/ref/runner
 
       Global Options:
         --log     Logging verbosity

bin/cml/tensorboard/connect.js

@@ -73,8 +73,12 @@ const launchAndWaitLink = async (opts = {}) => {
 };
 
 exports.tbLink = tbLink;
+
+const DESCRIPTION = 'Connect to tensorboard.dev and get a link';
+const DOCSURL = 'https://cml.dev/doc/ref/tensorboard';
+
 exports.command = 'connect';
-exports.description = 'Connect to tensorboard.dev and get a link';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { file, credentials, name, description } = opts;
@@ -144,3 +148,4 @@ exports.options = kebabcaseKeys({
     telemetryData: 'name'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/workflow/rerun.js

@@ -1,7 +1,10 @@
 const kebabcaseKeys = require('kebabcase-keys');
 
+const DESCRIPTION = 'Rerun a workflow given the jobId or workflowId';
+const DOCSURL = 'https://cml.dev/doc/ref/workflow';
+
 exports.command = 'rerun';
-exports.description = 'Rerun a workflow given the jobId or workflowId';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { cml } = opts;
@@ -20,3 +23,5 @@ exports.options = kebabcaseKeys({
     description: 'Run identifier to be rerun'
   }
 });
+
+exports.DOCSURL = DOCSURL;