From 2bf7da88d2f131246f791fec2ba59598c7f933d2 Mon Sep 17 00:00:00 2001 From: Kai Salmen Date: Tue, 18 Jun 2024 23:31:08 +0200 Subject: [PATCH] doc: Update generator documentation inside the repo --- packages/generator-langium/src/index.ts | 6 ++- .../generator-langium/templates/README.md | 16 ++++++++ .../templates/packages/cli/README.md | 19 +++++++++ .../packages/extension/langium-quickstart.md | 37 +++++++++++++++++ .../packages/language/.vscode-extensions.json | 10 ----- .../templates/packages/language/README.md | 17 ++++++++ .../packages/language/langium-quickstart.md | 41 ------------------- .../templates/packages/web/README.md | 18 ++++++++ .../test/yeoman-generator.test.ts | 10 ++++- 9 files changed, 120 insertions(+), 54 deletions(-) create mode 100644 packages/generator-langium/templates/README.md create mode 100644 packages/generator-langium/templates/packages/cli/README.md create mode 100644 packages/generator-langium/templates/packages/extension/langium-quickstart.md delete mode 100644 packages/generator-langium/templates/packages/language/.vscode-extensions.json create mode 100644 packages/generator-langium/templates/packages/language/README.md delete mode 100644 packages/generator-langium/templates/packages/language/langium-quickstart.md create mode 100644 packages/generator-langium/templates/packages/web/README.md diff --git a/packages/generator-langium/src/index.ts b/packages/generator-langium/src/index.ts index 6e21d1a82..2a882699a 100644 --- a/packages/generator-langium/src/index.ts +++ b/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', diff --git a/packages/generator-langium/templates/README.md b/packages/generator-langium/templates/README.md new file mode 100644 index 000000000..df087c223 --- /dev/null +++ b/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. diff --git a/packages/generator-langium/templates/packages/cli/README.md b/packages/generator-langium/templates/packages/cli/README.md new file mode 100644 index 000000000..1bf4b8a6c --- /dev/null +++ b/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. diff --git a/packages/generator-langium/templates/packages/extension/langium-quickstart.md b/packages/generator-langium/templates/packages/extension/langium-quickstart.md new file mode 100644 index 000000000..5a1ba5105 --- /dev/null +++ b/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 ` 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 `/.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 diff --git a/packages/generator-langium/templates/packages/language/.vscode-extensions.json b/packages/generator-langium/templates/packages/language/.vscode-extensions.json deleted file mode 100644 index 7f73a0a33..000000000 --- a/packages/generator-langium/templates/packages/language/.vscode-extensions.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - // See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations. - // Extension identifier format: ${publisher}.${name}. Example: vscode.csharp - - // List of extensions which should be recommended for users of this workspace. - "recommendations": [ - "langium.langium-vscode", - "vitest.explorer" - ] -} diff --git a/packages/generator-langium/templates/packages/language/README.md b/packages/generator-langium/templates/packages/language/README.md new file mode 100644 index 000000000..57396c287 --- /dev/null +++ b/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. diff --git a/packages/generator-langium/templates/packages/language/langium-quickstart.md b/packages/generator-langium/templates/packages/language/langium-quickstart.md deleted file mode 100644 index 746d3ceb8..000000000 --- a/packages/generator-langium/templates/packages/language/langium-quickstart.md +++ /dev/null @@ -1,41 +0,0 @@ -# Welcome to your Langium VS Code Extension - -## What's in the folder - -This folder contains all necessary files for your language extension. - -* `package.json` - the manifest file in which you declare your language support. -* `language-configuration.json` - the language configuration used in the VS Code editor, defining the tokens that are used for comments and brackets. -* `src/extension/main.ts` - the main code of the extension, which is responsible for launching a language server and client. -* `src/language/<%= language-id %>.langium` - the grammar definition of your language. -* `src/language/main.ts` - the entry point of the language server process. -* `src/language/<%= language-id %>-module.ts` - the dependency injection module of your language implementation. Use this to register overridden and added services. -* `src/language/<%= language-id %>-validator.ts` - an example validator. You should change it to reflect the semantics of your language. -* `src/cli/main.ts` - the entry point of the command line interface (CLI) of your language. -* `src/cli/generator.ts` - the code generator used by the CLI to write output files from DSL documents. -* `src/cli/util.ts` - utility code for the CLI. - -## 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 ` 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 `/.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 diff --git a/packages/generator-langium/templates/packages/web/README.md b/packages/generator-langium/templates/packages/web/README.md new file mode 100644 index 000000000..d9f3901cb --- /dev/null +++ b/packages/generator-langium/templates/packages/web/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 diff --git a/packages/generator-langium/test/yeoman-generator.test.ts b/packages/generator-langium/test/yeoman-generator.test.ts index 6cf1c54fe..4b354a479 100644 --- a/packages/generator-langium/test/yeoman-generator.test.ts +++ b/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,7 +77,8 @@ 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) => [ @@ -81,6 +86,7 @@ describe('Check yeoman generator works', () => { 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'