Improved tutorial definitions for better docs inclusion (#3342)

Author: AndreasArvidsson

cursorless-talon/src/cursorless.py

@@ -34,7 +34,7 @@ def private_cursorless_show_command_statistics():
     def private_cursorless_start_tutorial():
         """Start the introductory Cursorless tutorial"""
         actions.user.private_cursorless_run_rpc_command_no_wait(
-            "cursorless.tutorial.start", "tutorial-1-basics"
+            "cursorless.tutorial.start", "1-introduction"
         )
 
     def private_cursorless_tutorial_next():

packages/app-web-docs/src/docs/user/README.md

@@ -5,7 +5,7 @@ sidebar_position: 1
 
 # Cursorless
 
-Welcome to Cursorless! If you're new, start with the [learning resources](./learning-resources.md) or the [how-to guides](./how-to.md).
+Welcome to Cursorless! If you're new, start with the [tutorial](./tutorial/README.mdx) or the [learning resources](./learning-resources.md).
 
 This guide assumes you've already [installed Cursorless](./installation.md).
 

…docs/src/docs/user/tutorial/1-basics.mdx …rc/docs/user/tutorial/1-introduction.mdxpackages/app-web-docs/src/docs/user/tutorial/1-basics.mdx renamed to packages/app-web-docs/src/docs/user/tutorial/1-introduction.mdx packages/app-web-docs/src/docs/user/tutorial/1-basics.mdx renamed to packages/app-web-docs/src/docs/user/tutorial/1-introduction.mdx

@@ -1,8 +1,10 @@
 import { RecordedTestVisualizer, RecordedTestVisualizerOptions, RecordedTestVisualizerProvider } from "@site/src/docs/components/RecordedTestVisualizer";
-import recordedTests from "./fixtures/1-basics.json";
+import recordedTests from "./fixtures/1-introduction.json";
 
 # 1. Introduction
 
+This tutorial will teach you the basics of Cursorless.
+
 <RecordedTestVisualizerProvider recordedTests={recordedTests}>
 
 <RecordedTestVisualizerOptions />
@@ -11,78 +13,76 @@ import recordedTests from "./fixtures/1-basics.json";
 
 Say `"take cap"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-1-basics/takeCap" />
+<RecordedTestVisualizer fixtureName="tutorial/1-introduction/takeCap" />
 
 ## Step 2
 
 Well done! 🙌 You just used the code word for 'c', "cap", to refer to the word with a gray hat over the 'c'.
 
 When a hat is not gray, we say its color: say `"take blue sun"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-1-basics/takeBlueSun" />
+<RecordedTestVisualizer fixtureName="tutorial/1-introduction/takeBlueSun" />
 
 ## Step 3
 
 Selecting a single token is great, but often we need something bigger.
 
 Say `"take harp past drum"` to select a range.
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-1-basics/takeHarpPastDrum" />
+<RecordedTestVisualizer fixtureName="tutorial/1-introduction/takeHarpPastDrum" />
 
 ## Step 4
 
 Despite its name, one of the most powerful aspects of Cursorless is the ability to use more than one cursor.
 
 Let's try that: `"take near and sun"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-1-basics/takeNearAndSun" />
+<RecordedTestVisualizer fixtureName="tutorial/1-introduction/takeNearAndSun" />
 
 ## Step 5
 
 But let's show that Cursorless can live up to its name: we can say `"chuck trap"` to delete a word without ever moving our cursor.
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-1-basics/chuckTrap" />
+<RecordedTestVisualizer fixtureName="tutorial/1-introduction/chuckTrap" />
 
 ## Step 6
 
 Tokens are great, but they're just one way to think of a document.
 
 Let's try working with lines: `"chuck line odd"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-1-basics/chuckLineOdd" />
+<RecordedTestVisualizer fixtureName="tutorial/1-introduction/chuckLineOdd" />
 
 ## Step 7
 
 We can also use "line" to refer to the line containing our cursor: `"take line"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-1-basics/takeLine" />
+<RecordedTestVisualizer fixtureName="tutorial/1-introduction/takeLine" />
 
 ## Step 8
 
 You now know how to select and delete; let's give you a couple more actions to play with: say "pre" to place the cursor before a target, as in `"pre urge"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-1-basics/preUrge" />
+<RecordedTestVisualizer fixtureName="tutorial/1-introduction/preUrge" />
 
 ## Step 9
 
 Say "post" to place the cursor after a target: `"post air"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-1-basics/postAir" />
+<RecordedTestVisualizer fixtureName="tutorial/1-introduction/postAir" />
 
 ## Step 10
 
 Say "change" to delete a word and move your cursor to where it used to be: `"change sit"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-1-basics/changeSit" />
+<RecordedTestVisualizer fixtureName="tutorial/1-introduction/changeSit" />
 
 ## Step 11
 
 And that wraps up unit 1 of the Cursorless tutorial! Next time, we'll write some code 🙌.
 
-Feel free to keep playing with this document, then say `"tutorial next"` to continue.
+</RecordedTestVisualizerProvider>
 
-:::note
-This step has no visualisation. To get the full experience try the interactive tutorial in VS Code by saying `"cursorless tutorial"`.
-:::
+## Next tutorial: 2. Basic coding
 
-</RecordedTestVisualizerProvider>
+[Continue to Basic coding](./2-basic-coding.mdx) - This tutorial will teach you the basics of coding with Cursorless.

packages/app-web-docs/src/docs/user/tutorial/2-basic-coding.mdx

@@ -3,6 +3,8 @@ import recordedTests from "./fixtures/2-basic-coding.json";
 
 # 2. Basic coding
 
+This tutorial will teach you the basics of coding with Cursorless.
+
 <RecordedTestVisualizerProvider recordedTests={recordedTests}>
 
 <RecordedTestVisualizerOptions />
@@ -11,80 +13,56 @@ import recordedTests from "./fixtures/2-basic-coding.json";
 
 When editing code, we often think in terms of statements, functions, etc. Let's clone a statement: `"clone state sit"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-2-basic-coding/cloneStateInk" />
+<RecordedTestVisualizer fixtureName="tutorial/2-basic-coding/cloneStateInk" />
 
 ## Step 2
 
-"state" is one of many scopes supported by Cursorless. To see all available scopes, have a look at the Scopes section below, and use the "visualize" command to see them live: `"visualize funk"`
-
-:::note
-This step has no visualisation. To get the full experience try the interactive tutorial in VS Code by saying `"cursorless tutorial"`.
-:::
-
-## Step 3
-
-Say `"visualize nothing"` to hide the visualization.
-
-:::note
-This step has no visualisation. To get the full experience try the interactive tutorial in VS Code by saying `"cursorless tutorial"`.
-:::
-
-## Step 4
-
 Cursorless tries its best to keep your commands short.
 
 In the following command, we just say "string" once, but Cursorless infers that both targets are strings: `"swap string air with whale"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-2-basic-coding/swapStringAirWithWhale" />
+<RecordedTestVisualizer fixtureName="tutorial/2-basic-coding/swapStringAirWithWhale" />
 
-## Step 5
+## Step 3
 
 Great. Let's learn a new action. The "pour" action lets you start editing a new line below any line on your screen: `"pour urge"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-2-basic-coding/pourUrge" />
+<RecordedTestVisualizer fixtureName="tutorial/2-basic-coding/pourUrge" />
 
-## Step 6
+## Step 4
 
 Now let's try applying a Cursorless action to the current line: `"dedent this"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-2-basic-coding/dedentThis" />
+<RecordedTestVisualizer fixtureName="tutorial/2-basic-coding/dedentThis" />
 
-## Step 7
+## Step 5
 
 Code reuse is a fact of life as a programmer. Cursorless makes this easy with the "bring" command: `"bring state urge"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-2-basic-coding/bringStateUrge" />
+<RecordedTestVisualizer fixtureName="tutorial/2-basic-coding/bringStateUrge" />
 
-## Step 8
+## Step 6
 
 "bring" also works with two targets just like "swap": `"bring blue cap to value red"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-2-basic-coding/bringBlueCapToValueRisk" />
+<RecordedTestVisualizer fixtureName="tutorial/2-basic-coding/bringBlueCapToValueRisk" />
 
-## Step 9
+## Step 7
 
 Cursorless tries its best to use its knowledge of programming languages to leave you with syntactically valid code.
 
 Note how it cleans up the comma here: `"chuck arg blue vest"`
 
-<RecordedTestVisualizer fixtureName="tutorial/tutorial-2-basic-coding/chuckArgueBlueVest" />
+<RecordedTestVisualizer fixtureName="tutorial/2-basic-coding/chuckArgueBlueVest" />
 
-## Step 10
+## Step 8
 
 We introduced a lot of different scopes today. If you're anything like us, you've already forgotten them all.
 
 The important thing to remember is that you can always say `"cursorless help"` to see a list.
 
-:::note
-This step has no visualisation. To get the full experience try the interactive tutorial in VS Code by saying `"cursorless tutorial"`.
-:::
-
-## Step 11
-
-As always, feel free to stick around and play with this file to practice what you've just learned. Happy coding 😊. Say `"tutorial next"` to get back home.
+## Step 9
 
-:::note
-This step has no visualisation. To get the full experience try the interactive tutorial in VS Code by saying `"cursorless tutorial"`.
-:::
+That wraps up the Basic coding tutorial. Happy coding 😊.
 
 </RecordedTestVisualizerProvider>

packages/app-web-docs/src/docs/user/tutorial/README.mdx

@@ -6,11 +6,11 @@ To follow along interactively, focus VS Code and say `"cursorless tutorial"`.
 
 ## 1. Introduction
 
-[Start Introduction](./1-basics.mdx)
+[Start Introduction](./1-introduction.mdx) - This tutorial will teach you the basics of Cursorless.
 
 ## 2. Basic coding
 
-[Start Basic coding](./2-basic-coding.mdx)
+[Start Basic coding](./2-basic-coding.mdx) - This tutorial will teach you the basics of coding with Cursorless.
 
 ## Use the interactive tutorial
 

…ocs/user/tutorial/fixtures/1-basics.json …er/tutorial/fixtures/1-introduction.jsonpackages/app-web-docs/src/docs/user/tutorial/fixtures/1-basics.json renamed to packages/app-web-docs/src/docs/user/tutorial/fixtures/1-introduction.json packages/app-web-docs/src/docs/user/tutorial/fixtures/1-basics.json renamed to packages/app-web-docs/src/docs/user/tutorial/fixtures/1-introduction.json

@@ -1,7 +1,7 @@
 [
 	{
-		"path": "tutorial/tutorial-1-basics/takeCap.yml",
-		"name": "tutorial/tutorial-1-basics/takeCap",
+		"path": "tutorial/1-introduction/takeCap.yml",
+		"name": "tutorial/1-introduction/takeCap",
 		"fixture": {
 			"languageId": "plaintext",
 			"command": {
@@ -629,8 +629,8 @@
 		}
 	},
 	{
-		"path": "tutorial/tutorial-1-basics/takeBlueSun.yml",
-		"name": "tutorial/tutorial-1-basics/takeBlueSun",
+		"path": "tutorial/1-introduction/takeBlueSun.yml",
+		"name": "tutorial/1-introduction/takeBlueSun",
 		"fixture": {
 			"languageId": "plaintext",
 			"command": {
@@ -1258,8 +1258,8 @@
 		}
 	},
 	{
-		"path": "tutorial/tutorial-1-basics/takeHarpPastDrum.yml",
-		"name": "tutorial/tutorial-1-basics/takeHarpPastDrum",
+		"path": "tutorial/1-introduction/takeHarpPastDrum.yml",
+		"name": "tutorial/1-introduction/takeHarpPastDrum",
 		"fixture": {
 			"languageId": "plaintext",
 			"command": {
@@ -1910,8 +1910,8 @@
 		}
 	},
 	{
-		"path": "tutorial/tutorial-1-basics/takeNearAndSun.yml",
-		"name": "tutorial/tutorial-1-basics/takeNearAndSun",
+		"path": "tutorial/1-introduction/takeNearAndSun.yml",
+		"name": "tutorial/1-introduction/takeNearAndSun",
 		"fixture": {
 			"languageId": "plaintext",
 			"command": {
@@ -2572,8 +2572,8 @@
 		}
 	},
 	{
-		"path": "tutorial/tutorial-1-basics/chuckTrap.yml",
-		"name": "tutorial/tutorial-1-basics/chuckTrap",
+		"path": "tutorial/1-introduction/chuckTrap.yml",
+		"name": "tutorial/1-introduction/chuckTrap",
 		"fixture": {
 			"languageId": "plaintext",
 			"command": {
@@ -3207,8 +3207,8 @@
 		}
 	},
 	{
-		"path": "tutorial/tutorial-1-basics/chuckLineOdd.yml",
-		"name": "tutorial/tutorial-1-basics/chuckLineOdd",
+		"path": "tutorial/1-introduction/chuckLineOdd.yml",
+		"name": "tutorial/1-introduction/chuckLineOdd",
 		"fixture": {
 			"languageId": "plaintext",
 			"command": {
@@ -3752,8 +3752,8 @@
 		}
 	},
 	{
-		"path": "tutorial/tutorial-1-basics/takeLine.yml",
-		"name": "tutorial/tutorial-1-basics/takeLine",
+		"path": "tutorial/1-introduction/takeLine.yml",
+		"name": "tutorial/1-introduction/takeLine",
 		"fixture": {
 			"languageId": "plaintext",
 			"command": {
@@ -4187,8 +4187,8 @@
 		}
 	},
 	{
-		"path": "tutorial/tutorial-1-basics/preUrge.yml",
-		"name": "tutorial/tutorial-1-basics/preUrge",
+		"path": "tutorial/1-introduction/preUrge.yml",
+		"name": "tutorial/1-introduction/preUrge",
 		"fixture": {
 			"languageId": "plaintext",
 			"command": {
@@ -4620,8 +4620,8 @@
 		}
 	},
 	{
-		"path": "tutorial/tutorial-1-basics/postAir.yml",
-		"name": "tutorial/tutorial-1-basics/postAir",
+		"path": "tutorial/1-introduction/postAir.yml",
+		"name": "tutorial/1-introduction/postAir",
 		"fixture": {
 			"languageId": "plaintext",
 			"command": {
@@ -5053,8 +5053,8 @@
 		}
 	},
 	{
-		"path": "tutorial/tutorial-1-basics/changeSit.yml",
-		"name": "tutorial/tutorial-1-basics/changeSit",
+		"path": "tutorial/1-introduction/changeSit.yml",
+		"name": "tutorial/1-introduction/changeSit",
 		"fixture": {
 			"languageId": "plaintext",
 			"command": {