doc: Update generator documentation inside the repo

Author: kaisalmen

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/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/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/language/.vscode-extensions.json

@@ -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/README.md

@@ -0,0 +1,18 @@
+# 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

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

@@ -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'