Update generator documentation in repo. At build:clean to generated p…

…roject

packages/generator-langium/src/index.ts

@@ -184,6 +184,7 @@ export class LangiumGenerator extends Generator {
             '.eslintrc.json',
             'tsconfig.json',
             'tsconfig.build.json',
+            'README.md',
             '.vscode'
         ];
         for (const path of baseFiles) {
@@ -200,7 +201,7 @@ export class LangiumGenerator extends Generator {
         const languageFiles = [
             'package.json',
             'langium-config.json',
-            'langium-quickstart.md',
+            'README.md',
             'tsconfig.json',
             'tsconfig.src.json',
             'vitest.config.ts',
@@ -241,6 +242,7 @@ export class LangiumGenerator extends Generator {
             const cliFiles = [
                 'package.json',
                 'tsconfig.json',
+                'README.md',
                 'bin',
                 'src'
             ];
@@ -260,6 +262,7 @@ export class LangiumGenerator extends Generator {
             const webFiles = [
                 'package.json',
                 'language-configuration.json',
+                'README.md',
                 'tsconfig.json',
                 'index.html',
                 'vite.config.ts',
@@ -282,6 +285,7 @@ export class LangiumGenerator extends Generator {
             const extensionFiles = [
                 '.vscodeignore',
                 'esbuild.mjs',
+                'langium-quickstart.md',
                 'language-configuration.json',
                 'package.json',
                 'tsconfig.json',

packages/generator-langium/templates/README.md

@@ -0,0 +1,16 @@
+# Workspace overview
+
+Depending on the selection during the project generation you will have one or more packages contained in the packages directory. Check the :
+
+- [packages/language](./packages/language/README.md) is always available and contains the language definition.
+- [packages/cli](./packages/cli/README.md) *Optional* Is only available if you chose to use the command-line interface.
+- [packages/extension](./packages/extension/langium-quickstart.md) *Optional* Contains the VSCode extension if you chose to create it.
+- [packages/web](./packages/web/README.md) *Optional* if selected contains the language server running in a web browser and a monaco-editor with language support similar to the onm from VSCode.
+
+## What's in the folder?
+
+- [.eslintrc.json](.eslintrc.json) - Configuration file for eslint
+- [.gitignore](.gitignore) - Files ignored by git
+- [package.json](./package.json) - The manifest file the main workspace package
+- [tsconfig.json](./tsconfig.json) - The base TypeScript compiler configuration
+- [tsconfig.build.json](./package.json) - Configuration used to build the complete source code.

packages/generator-langium/templates/package.json

@@ -5,8 +5,10 @@
     "type": "module",
     "private": true,
     "scripts": {
+        "clean": "npm run clean --workspaces",
         "watch": "tsc -b tsconfig.build.json --watch",
         "build": "tsc -b tsconfig.build.json && npm run build --workspaces",
+        "build:clean": "npm run clean && npm run build",
         "lint": "eslint src --ext ts",
         "langium:generate": "npm run --workspace packages/language langium:generate",
         "langium:watch": "npm run --workspace packages/language langium:watch"
@@ -16,6 +18,7 @@
         "@typescript-eslint/parser": "~7.13.0",
         "@typescript-eslint/eslint-plugin": "~7.13.0",
         "eslint": "~8.57.0",
+        "shx":  "~0.3.4",
         "typescript": "~5.4.5"
     },
     "volta": {

packages/generator-langium/templates/packages/cli/README.md

@@ -0,0 +1,19 @@
+# Command-line interface (CLI)
+
+Check [this part](https://langium.org/docs/learn/minilogo/customizing_cli/) of the Langium Minilogo Tutorial as a useful guide to the CLI.
+
+## What's in the folder?
+
+- [package.json](./package.json) - The manifest file of your cli package.
+- [tsconfig.src.json](./tsconfig.src.json) - The package specific TypeScript compiler configuration extending the [base config](../../tsconfig.json)
+- [tsconfig.json](./tsconfig.json) - TypeScript compiler configuration options required for proper functionality of VSCode.
+- [src/cli/main.ts](src/cli/main.ts) - the entry point of the command line interface (CLI) of your language.
+- [src/cli/generator.ts](src/cli/generator.ts) - the code generator used by the CLI to write output files from DSL documents.
+- [src/cli/util.ts](src/cli/util.ts) - utility code for the CLI.
+
+If you selected the test option as well, then you have the following for file as well:
+
+- [tsconfig.test.json](./tsconfig.test.json) - The package specific TypeScript compiler configuration for the unit tests extending the [tsconfig.src.config](tsconfig.src.json)
+- [test/linking.test.ts](test/linking.test.ts) - Unit tests checking linking.
+- [test/parsing.test.ts](test/parsing.test.ts) - Unit tests regarding parsing.
+- [test/validating.test.ts](test/validating.test.ts) - Unit tests regarding validation.

packages/generator-langium/templates/packages/cli/package.json

@@ -15,7 +15,9 @@
         "<%= language-id %>-cli": "./bin/cli.js"
     },
     "scripts": {
-        "build": "echo 'No build step'"
+        "clean": "shx rm -fr *.tsbuildinfo out",
+        "build": "echo 'No build step'",
+        "build:clean": "npm run clean && npm run build"
     },
     "dependencies": {
         "<%= extension-name %>-language": "0.0.1",

packages/generator-langium/templates/packages/extension/langium-quickstart.md

@@ -0,0 +1,37 @@
+# Langium VS Code Extension
+
+Welcome to your Langium VSCode extension. This folder contains all necessary files for your language extension.
+
+## What's in the folder?
+
+- [package.json](./package.json) - the manifest file in which you declare your language support.
+- [tsconfig.json](./tsconfig.json) - The packages specific TypeScript compiler configuration extending the [base config](../../tsconfig.json)
+- [esbuid.mjs](esbuild.mjs) - Configuration file for esbuild that is used to create the VSCode extension bundle.
+- [language-configuration.json](language-configuration.json) - the language configuration used in the VS Code editor, defining the tokens that are used for comments and brackets.
+- [src/language/main.ts](src/language/main.ts) - the entry point of the language server process.
+- [src/extension/main.ts](src/extension/main.ts) - the main code of the extension, which is responsible for launching a language server and client.
+
+## Get up and running straight away
+
+- Run `npm run langium:generate` to generate TypeScript code from the grammar definition.
+- Run `npm run build` to compile all TypeScript code.
+- Press `F5` to open a new window with your extension loaded.
+- Create a new file with a file name suffix matching your language.
+- Verify that syntax highlighting, validation, completion etc. are working as expected.
+- Run `node ./bin/cli` to see options for the CLI; `node ./bin/cli generate <file>` generates code for a given DSL file.
+
+## Make changes
+
+- Run `npm run watch` to have the TypeScript compiler run automatically after every change of the source files.
+- Run `npm run langium:watch` to have the Langium generator run automatically after every change of the grammar declaration.
+- You can relaunch the extension from the debug toolbar after making changes to the files listed above.
+- You can also reload (`Ctrl+R` or `Cmd+R` on Mac) the VS Code window with your extension to load your changes.
+
+## Install your extension
+
+- To start using your extension with VS Code, copy it into the `<user home>/.vscode/extensions` folder and restart Code.
+- To share your extension with the world, read the [VS Code documentation](https://code.visualstudio.com/api/working-with-extensions/publishing-extension) about publishing an extension.
+
+## To Go Further
+
+Documentation about the Langium framework is available at <https://langium.org>

packages/generator-langium/templates/packages/extension/package.json

@@ -27,8 +27,10 @@
     ],
     "main": "./out/extension/main.cjs",
     "scripts": {
+        "clean": "shx rm -fr *.tsbuildinfo out",
         "vscode:prepublish": "npm run build && npm run lint",
         "build": "tsc -b tsconfig.json && node esbuild.mjs",
+        "build:clean": "npm run clean && npm run build",
         "watch": "concurrently -n tsc,esbuild -c blue,yellow \"tsc -b tsconfig.json --watch\" \"node esbuild.mjs --watch\""
     },
     "dependencies": {

packages/generator-langium/templates/packages/language/README.md

@@ -0,0 +1,17 @@
+# The mandatory language package
+
+As a good entry point to our documentation, please use to this [guide](https://langium.org/docs/learn/workflow/write_grammar/).
+
+## What's in the folder?
+
+- [package.json](./package.json) - The manifest file of your language package.
+- [tsconfig.json](./tsconfig.json) - The packages specific TypeScript compiler configuration extending the [base config](../../tsconfig.json)
+- [src/<%= language-id %>.langium](src/<%= language-id %>.langium) -  the grammar definition of your language
+- [src/<%= language-id %>-module.ts](src/<%= language-id %>-module.ts) - the dependency injection module of your language implementation. Use this to register overridden and added services.
+- [src/<%= language-id %>-validator.ts](src/<%= language-id %>-validator.ts) - an example validator. You should change it to reflect the semantics of your language
+- [src/generated/ast.ts](src/generated/ast.ts) - Generated AST
+- [src/generated/grammar.ts](src/generated/grammar.ts) - Generated Grammar
+- [src/generated/module.ts](src/generated/module.ts) - Generated Module
+- [src/syntaxes/<%= language-id %>.monarch.ts](src/syntaxes/<%= language-id %>.monarch.ts) - Monarch based syntax highlighting instructions
+- [syntaxes/<%= language-id %>.tmLanguage.json](syntaxes/<%= language-id %>.tmLanguage.json) - Textmate based syntax highlighting instructions
+- [src/index.ts](src/index.ts) Defines what is exported to other packages.

packages/generator-langium/templates/packages/language/package.json

@@ -26,12 +26,14 @@
       }
     },
     "scripts": {
+        "clean": "shx rm -fr *.tsbuildinfo out",
         "build": "echo 'No build step'",
+        "build:clean": "npm run clean && npm run build",
         "langium:generate": "langium generate",
         "langium:watch": "langium generate --watch"
     },
     "dependencies": {
-        "langium": "~3.0.0"        
+        "langium": "~3.0.0"
     },
     "devDependencies": {
         "langium-cli": "~3.0.3"

packages/generator-langium/templates/packages/web/README.md

@@ -0,0 +1,35 @@
+# Web-based editor and language server
+
+How the web based editor works is well defined [here](https://langium.org/docs/learn/minilogo/langium_and_monaco).
+
+## What's in the folder?
+
+- [index.html](index.html) - Entry page that let's you decide which web editor version is used.
+- [language-configuration.json](language-configuration.json) - the language configuration used in the web editor, defining the tokens that are used for comments and brackets.
+- [package.json](./package.json) - The manifest file of your web editor package.
+- [src/main-browser.ts](src/main-browser.ts) - The the language server running in a web worker.
+- [src/setupClassic.ts](src/setupClassic.ts) - Create monaco-editor with classic configuration (monarch sytax highlighting)
+- [src/setupCommon.ts](src/setupCommon.ts) - Common settings for monaco-editor
+- [src/setupExtended.ts](src/setupExtended.ts) - Create monaco-editor with extended configuration (textmate sytax highlighting)
+- [static/monacoClassic.html](static/monacoClassic.html) - Page for classic monaco-editor
+- [static/monacoExtended.html](static/monacoExtended.html) - Page for extended monaco-editor
+- [static/styles.css](static/styles.css) - Stylesheets used by the HTML pages
+- [tsconfig.json](./tsconfig.json) - The packages specific TypeScript compiler configuration extending the [base config](../../tsconfig.json)
+- [vite.config.ts](vite.config.ts) - Vite/rollup production build instructions
+
+## Run the web application
+
+The generation post-step ensure that the whole project is built.
+You can run chose to run the application either in development mode (code changes are directly available in the application) or production mode (bundled).
+
+For development:
+
+```shell
+npm run dev
+```
+
+For production:
+
+```shell
+npm run serve
+```

packages/generator-langium/templates/packages/web/package.json

@@ -11,7 +11,9 @@
         "src"
     ],
     "scripts": {
+        "clean": "shx rm -fr *.tsbuildinfo out dist",
         "build": "vite build",
+        "build:clean": "npm run clean && npm run build",
         "dev": "vite",
         "dev:debug": "vite --debug --force",
         "serve": "vite preview"

packages/generator-langium/test/yeoman-generator.test.ts

@@ -33,16 +33,19 @@ describe('Check yeoman generator works', () => {
         targetRoot + '/tsconfig.build.json',
         targetRoot + '/tsconfig.json',
         targetRoot + '/package.json',
+        targetRoot + '/README.md',
         targetRoot + '/.vscode/extensions.json',
         targetRoot + '/.vscode/launch.json',
         targetRoot + '/.vscode/tasks.json',
+        targetRoot + '/packages/language/README.md',
         targetRoot + '/packages/language/src/hello-world-module.ts',
         targetRoot + '/packages/language/src/hello-world-validator.ts',
         targetRoot + '/packages/language/src/hello-world.langium',
         targetRoot + '/packages/language/src/syntaxes/hello-world.monarch.ts',
         targetRoot + '/packages/language/src/generated/ast.ts',
         targetRoot + '/packages/language/src/generated/grammar.ts',
-        targetRoot + '/packages/language/src/generated/module.ts'
+        targetRoot + '/packages/language/src/generated/module.ts',
+        targetRoot + '/packages/language/syntaxes/hello-world.tmLanguage.json'
     ];
 
     const filesTest = (targetRoot: string) => [
@@ -57,6 +60,7 @@ describe('Check yeoman generator works', () => {
         targetRoot + '/packages/cli/src/util.ts',
         targetRoot + '/packages/cli/src/generator.ts',
         targetRoot + '/packages/cli/src/main.ts',
+        targetRoot + '/packages/cli/README.md',
         targetRoot + '/packages/cli/package.json',
         targetRoot + '/packages/cli/tsconfig.json'
     ];
@@ -73,14 +77,16 @@ describe('Check yeoman generator works', () => {
         targetRoot + '/packages/web/language-configuration.json',
         targetRoot + '/packages/web/package.json',
         targetRoot + '/packages/web/tsconfig.json',
-        targetRoot + '/packages/web/vite.config.ts'
+        targetRoot + '/packages/web/vite.config.ts',
+        targetRoot + '/packages/web/README.md',
     ];
 
     const filesExtension = (targetRoot: string) => [
         targetRoot + '/packages/extension/src/extension/main.ts',
         targetRoot + '/packages/extension/src/language/main.ts',
         targetRoot + '/packages/extension/.vscodeignore',
         targetRoot + '/packages/extension/esbuild.mjs',
+        targetRoot + '/packages/extension/langium-quickstart.md',
         targetRoot + '/packages/extension/language-configuration.json',
         targetRoot + '/packages/extension/package.json',
         targetRoot + '/packages/extension/tsconfig.json'
@@ -238,8 +244,10 @@ const PACKAGE_JSON_EXPECTATION: Record<string, any> = {
     type: 'module',
     private: true,
     scripts: {
+        'clean': 'npm run clean --workspaces',
         'watch': 'tsc -b tsconfig.build.json --watch',
         'build': 'tsc -b tsconfig.build.json && npm run build --workspaces',
+        'build:clean': 'npm run clean && npm run build',
         'lint': 'eslint src --ext ts',
         'langium:generate': 'npm run --workspace packages/language langium:generate',
         'langium:watch': 'npm run --workspace packages/language langium:watch'
@@ -249,6 +257,7 @@ const PACKAGE_JSON_EXPECTATION: Record<string, any> = {
         '@typescript-eslint/eslint-plugin': '~7.13.0',
         '@typescript-eslint/parser': '~7.13.0',
         'eslint': '~8.57.0',
+        'shx':  '~0.3.4',
         'typescript': '~5.4.5'
     },
     volta: {
@@ -274,7 +283,9 @@ const PACKAGE_JSON_EXPECTATION_CLI: Record<string, any> = {
         'hello-world-cli': './bin/cli.js'
     },
     scripts: {
-        'build': "echo 'No build step'"
+        'clean': 'shx rm -fr *.tsbuildinfo out',
+        'build': "echo 'No build step'",
+        'build:clean': 'npm run clean && npm run build'
     },
     dependencies: {
         'hello-world-language': '0.0.1',
@@ -298,7 +309,9 @@ const PACKAGE_JSON_EXPECTATION_WEB: Record<string, any> = {
     },
     files: ['out', 'src'],
     scripts: {
+        'clean': 'shx rm -fr *.tsbuildinfo out dist',
         'build': 'vite build',
+        'build:clean': 'npm run clean && npm run build',
         'dev': 'vite',
         'dev:debug': 'vite --debug --force',
         'serve': 'vite preview'
@@ -351,8 +364,10 @@ const PACKAGE_JSON_EXPECTATION_EXTENSION: Record<string, any> = {
     ],
     main: './out/extension/main.cjs',
     scripts: {
+        'clean': 'shx rm -fr *.tsbuildinfo out',
         'vscode:prepublish': 'npm run build && npm run lint',
         'build': 'tsc -b tsconfig.json && node esbuild.mjs',
+        'build:clean': 'npm run clean && npm run build',
         'watch': 'concurrently -n tsc,esbuild -c blue,yellow "tsc -b tsconfig.json --watch" "node esbuild.mjs --watch"'
     },
     dependencies: {