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:

shell
1npm 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:

typescript
1import {Tutorial} from '@datagrok-libraries/tutorials';
2
3export class CustomTutorial extends Tutorial {
4  get name(): string { return 'Custom Tutorial'; }
5  get description(): string { return 'Teaches users about a feature'; }
6
7  protected async _run(): Promise<void> {
8    // Define steps using this.action() and helper methods
9    // Steps are event-based and can include interactive hints
10  }
11}

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:

typescript
1import {CustomTutorial} from './tutorials/custom-tutorial';
2
3//tags: tutorial
4//meta.icon: images/custom-tutorial.png
5//meta.name: Custom Tutorial
6//meta.track: Test Track
7//description: This tutorial illustrates a new feature
8//output: object
9export function registerTutorial() {
10  return new CustomTutorial();
11}

Required annotations

Optional annotations

4. Register a track (optional)

To define a custom track that groups tutorials:

typescript
1import {Track} from '@datagrok-libraries/tutorials';
2
3//tags: track
4//help-url: https://datagrok.ai/help
5//output: object
6//meta.name: Test Track
7export function registerTrack() {
8  return new Track('Test Track', [], 'https://datagrok.ai/help');
9}

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

shell
1webpack
2grok 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.