Adds more documentation for the guide/ section on the Lute website by Vighnesh-V · Pull Request #884 · luau-lang/lute

Vighnesh-V · 2026-03-17T22:06:27Z

Inspired by the Rust Book , this PR adds more documentation to the guide section to get new users up and running with programming with Lute. The rough layout is:

Hello World (directory structure, lute setup for lsp support).
Writing a guessing game (input output, requiring libraries, the difference between things Lute provides as libraries and what Luau provides as builtins, argument handling)
Writing tests (brief walkthrough of how to write tests + directory structure)
Code transforms! How do you write and run them, what are the kinds of code transforms (visitor / query based).
Developer Tooling - how can you incorporate all the awesome things we've done into your workflow.

Splitting this PR up:

annieetang

thanks for writing this! will be super valuable to have on the site.

are the pages under dev-tooling intended to replace the CLI reference? if not, are there duplicate information that we can cut down and could we link them together? if dev-tooling/lute-lint can have a hyperlink or a section pointing users to the lute lint CLI reference if they're interested in learning more, etc. (same with the other tooling, and anything in the other pages that readers could read more about)

also it would be nice if we could split this pr up a bit, it's pretty dense and I think we could add these to the site in parts 😅

annieetang · 2026-03-18T15:43:15Z

docs/guide/dev-tooling/lute-lint.md

+- TODO: add linter format documentation
+- TODO: add explanation of how / where to add custom rules


shld this be commented out?

I actually want to leave the TODO's here as artifacts for what our documentation is missing.

oh ok can we write like "In progress..." or "Check back soon" something so it's a little more formal

annieetang · 2026-03-18T15:45:42Z

docs/guide/writing-tests/index.md

+order: 5
+---
+
+# Writing Tests


should the "Writing Tests" section be underneath "Developer Tooling / Lute Test"? or if we could mention this section in the Lute Test page so anyone reading can know where to find examples / how to write the tests

I think this should be it's own section as it's a tutorial on how to actually use the standard library to write tests (and it's related to the previous section). I'll link it.

annieetang · 2026-03-18T15:47:42Z

docs/guide/writing-tests/index.md

+
+As mentioned [here](../dev-tooling/index.md), `lute` comes with a builtin utility for discovering and running tests. In this chapter we'll see how you can write tests against this framework and execute them. This can help you improve your confidence in the correctness of your code. We'll look at how we could test the code from the guessing game chapter, specifically the code that handles argument parsing.
+
+To get started, set up a project structure that has these files:


Could we have some subheadings for the different phases and examples? would be a little easier to read and re-reference

annieetang · 2026-03-18T15:48:43Z

docs/guide/writing-tests/snapshot-testing.md

+---
+
+# Snapshot Testing (Experimental)
+TODO


if we don't want to leave the TODO on the actual site, could we keep this an empty page or something like 'check back later' / 'in progress'?

annieetang · 2026-03-18T16:10:12Z

docs/guide/hello-world.md

+
+# Hello World!
+
+We're going to walk through the creation of a simple program using Lute. To start with, create a folder for your project with:


do we have an intro anywhere for what Lute is / would here be a good place for a quick welcome and brief explanation for why someone would want to use lute, then we can get into the setup?

We should have this, but I'm not going to add it at this time, since the place I think we are deficient in is informing users of all the cool stuff we've implemented and how to use it. A foreword / intro can come a bit later I think

sg! we can also put this intro on the home page

annieetang · 2026-03-18T16:11:45Z

docs/guide/writing-a-guessing-game.md

+## TODOS:
+- Perhaps implement a lute new \<proj\> command, that creates a main.luau file, setups a luaurc, creates a tests directory?


same here, do we want to keep this commented out?

Vighnesh-V · 2026-03-18T16:31:54Z

Going to address the comments in a single pass here:

I'll split this PR up since it's a bit dense
The CLI Reference is intended to be an overview of the different command line options associated with these subcommands. There might be duplicate information, but it's not a replacement for an actual introduction or tutorial. We should link to the appropriate sections though.
The motivation for this guide is to be a 1000 foot view / tutorial for how you can get started using Lute to write Luau programs and be more productive by making full use of the tooling provided. One thing we don't do a great job of atm is advertising exactly what we provide out of the box, and why you should use it, which is what the developer tooling section is meant to address.

Documentation writing

Vighnesh-V added this to the Release A milestone Mar 17, 2026

Vighnesh-V requested a review from Nicell March 17, 2026 22:06

Vighnesh-V self-assigned this Mar 17, 2026

Vighnesh-V added the documentation Improvements or additions to documentation label Mar 17, 2026

annieetang reviewed Mar 18, 2026

View reviewed changes

Vighnesh-V added 2 commits March 20, 2026 14:38

Adds a tutorial on how to write tests

ca385f5

Documentation writing

pr feedback

6e21ae3

Vighnesh-V force-pushed the write-docs-lute branch from ad05790 to 6e21ae3 Compare March 20, 2026 22:39

another

4d064a9

		- TODO: add linter format documentation
		- TODO: add explanation of how / where to add custom rules


		As mentioned [here](../dev-tooling/index.md), `lute` comes with a builtin utility for discovering and running tests. In this chapter we'll see how you can write tests against this framework and execute them. This can help you improve your confidence in the correctness of your code. We'll look at how we could test the code from the guessing game chapter, specifically the code that handles argument parsing.

		To get started, set up a project structure that has these files:


		# Hello World!

		We're going to walk through the creation of a simple program using Lute. To start with, create a folder for your project with:

		## TODOS:
		- Perhaps implement a lute new \<proj\> command, that creates a main.luau file, setups a luaurc, creates a tests directory? No newline at end of file

Conversation

Vighnesh-V commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

annieetang left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Vighnesh-V commented Mar 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Vighnesh-V commented Mar 17, 2026 •

edited

Loading