Write Tutorial

Help the user create an interactive tutorial that educates users about Datagrok platform features.

Usage

/write-tutorial [tutorial-name] [--package <package-name>] [--track <track-name>]

Instructions

1. Install the tutorials library

The package must depend on @datagrok-libraries/tutorials:

npm install @datagrok-libraries/tutorials

2. Create the Tutorial subclass

Create a TypeScript file (e.g., src/tutorials/custom-tutorial.ts) with a class extending Tutorial:

import {Tutorial} from '@datagrok-libraries/tutorials';

export class CustomTutorial extends Tutorial {
  get name(): string { return 'Custom Tutorial'; }
  get description(): string { return 'Teaches users about a feature'; }

  protected async _run(): Promise<void> {
    // Define steps using this.action() and helper methods
    // Steps are event-based and can include interactive hints
  }
}

Key points:

• Override name and description getters.
• Implement the _run method with a sequence of steps.
• Steps use the action method or helper methods that call it internally.
• Steps can include interactive hints and detailed descriptions.

3. Register the tutorial in package.ts

Add a registration function with metadata annotations:

import {CustomTutorial} from './tutorials/custom-tutorial';

//tags: tutorial
//meta.icon: images/custom-tutorial.png
//meta.name: Custom Tutorial
//meta.track: Test Track
//description: This tutorial illustrates a new feature
//output: object
export function registerTutorial() {
  return new CustomTutorial();
}

Required annotations

Optional annotations

4. Register a track (optional)

To define a custom track that groups tutorials:

import {Track} from '@datagrok-libraries/tutorials';

//tags: track
//help-url: https://datagrok.ai/help
//output: object
//meta.name: Test Track
export function registerTrack() {
  return new Track('Test Track', [], 'https://datagrok.ai/help');
}

Track registration annotations:

• tags: track (required)
• meta.name (required): track display name
• help-url (required): link to documentation
• output: object (required)

5. Control visibility of standard tutorials

The Tutorials package provides default tracks (e.g., Exploratory Data Analysis, Data Access). Their visibility can be controlled at the user group level via package settings.

6. Build and publish

webpack
grok publish dev

Behavior

• Ask the user for the tutorial name, description, target package, and which track it should belong to.
• Ask what interactive steps the tutorial should include.
• Generate the Tutorial subclass with _run implementation.
• Add the registration function to package.ts with correct annotations.
• If the user wants a new track, also generate the track registration function.
• Ensure the @datagrok-libraries/tutorials dependency is present in package.json.
• Remind the user that without meta.track, tutorials get their own package-specific track.
• Follow project coding conventions: no excessive comments, no curly brackets for one-line if/for, catch/else if on new lines.