Gradle Grammar-Kit Plugin docs (#793)

ijs.tree

@@ -385,5 +385,6 @@
       <toc-element toc-title="Frequently Asked Questions" id="tools_gradle_intellij_plugin_faq.md"/>
       <toc-element toc-title="Migration Guide from 0.x to 1.x" href="https://lp.jetbrains.com/gradle-intellij-plugin/"/>
     </toc-element>
+    <toc-element id="tools_gradle_grammar_kit_plugin.md" show-structure-depth="1" />
   </toc-element>
 </product-profile>

topics/appendix/tools/tools_gradle_grammar_kit_plugin.md

@@ -0,0 +1,285 @@
+[//]: # (title: Gradle IntelliJ Plugin)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+
+This Gradle plugin automates generating lexers and parsers to support the custom language development of plugins for IntelliJ-based IDEs when using Grammar-Kit.
+
+> Current Gradle Grammar-Kit Plugin version is ![GitHub Release](https://img.shields.io/github/release/jetbrains/gradle-grammar-kit-plugin.svg?style=flat-square)
+>
+{type="note"}
+
+> The plugin does not support two-pass generation. Therefore, it does not support method mixins.
+>
+{type="tip"}
+
+## Usage
+To enable this plugin in your Gradle-based project, register the plugin in the Gradle build script's `plugins` section:
+
+<tabs>
+<tab title="Kotlin">
+
+```kotlin
+plugins {
+  id("org.jetbrains.grammarkit") version "..."
+}
+```
+
+</tab>
+<tab title="Groovy">
+
+```groovy
+plugins {
+  id "org.jetbrains.grammarkit" version "..."
+}
+```
+
+</tab>
+</tabs>
+
+> This project requires `Gradle 6.7` or newer, however it is recommended to use the latest Gradle available.
+> Update it with:
+> ```Bash
+> ./gradlew wrapper --gradle-version=VERSION
+> ```
+>
+> See also: [Gradle Installation](https://gradle.org/install/) guide.
+>
+{type="tip"}
+
+> Please see [CONTRIBUTING](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/CONTRIBUTING.md) on how to submit feedback and contribute to this project.
+>
+> Before visiting the [Issue Tracker](https://github.com/JetBrains/gradle-intellij-plugin/issues), update both plugin and Gradle to the latest versions.
+>
+{type="tip"}
+
+
+## Grammar-Kit Extension
+After the Gradle Grammar-Kit Plugin is applied, the `grammarKit` extension can be used to configure the plugin and common settings of the provided tasks.
+
+**Example:**
+
+
+<tabs>
+<tab title="Kotlin">
+
+```kotlin
+grammarKit {
+  jflexRelease.set("1.7.0-1")
+  grammarKitRelease.set("2021.1.2")
+  intellijRelease.set("203.7717.81")
+}
+```
+
+</tab>
+<tab title="Groovy">
+
+```groovy
+grammarKit {
+  jflexRelease = "1.7.0-1"
+  grammarKitRelease = "2021.1.2"
+  intellijRelease = "203.7717.81"
+}
+```
+
+</tab>
+</tabs>
+
+
+### grammarKitRelease
+{id="grammar-kit-extension-grammarkitrelease"}
+
+The release version of the [Grammar-Kit](https://github.com/JetBrains/Grammar-Kit) to use.
+
+{style="narrow"}
+Type
+: `String`
+
+Default value
+: `2021.1.2`
+
+
+### jflexRelease
+{id="grammar-kit-extension-jflexrelease"}
+
+The version of the IntelliJ-patched JFlex, a [fork of JFlex](https://github.com/JetBrains/intellij-deps-jflex) lexer generator for IntelliJ Platform API.
+
+{style="narrow"}
+Type
+: `String`
+
+Default value
+: `1.7.0-1`
+
+
+### intellijRelease
+{id="grammar-kit-extension-intellijrelease"}
+
+An optional IntelliJ version to build the classpath for [`GenerateParser`](#) and [`GenerateLexer`](#) tasks.
+
+If provided, [`grammarKitRelease`](#grammar-kit-extension-grammarkitrelease) and [`jflexRelease`](#grammar-kit-extension-jflexrelease) properties are ignored as both dependencies will be provided from the given IntelliJ IDEA release.
+
+{style="narrow"}
+Type
+: `String`
+
+Default value
+: `null`
+
+
+## generateLexer Task
+{id="generatelexer-task"}
+
+The `generateLexer` task generates a lexer for the given grammar.
+The task is configured using common [`grammarKit`](#grammar-kit-extension) extension.
+
+
+### source
+{id="generatelexer-task-source"}
+
+The source Flex file to generate the lexer from.
+
+{style="narrow"}
+Required
+: `true`
+
+Type
+: `String`
+
+
+### targetDir
+{id="generatelexer-task-targetdir"}
+
+The path to the target directory for the generated lexer.
+
+{style="narrow"}
+Required
+: `true`
+
+Type
+: `String`
+
+
+### targetClass
+{id="generatelexer-task-targetclass"}
+
+The Java file name where the generated lexer will be written.
+
+{style="narrow"}
+Required
+: `true`
+
+Type
+: `String`
+
+
+### skeleton
+{id="generatelexer-task-skeleton"}
+
+An optional path to the skeleton file to use for the generated lexer.
+The path will be provided as `--skel` option.
+By default, it uses the <path>[idea-flex.skeleton](https://raw.github.com/JetBrains/intellij-community/master/tools/lexer/idea-flex.skeleton)</path> skeleton file.
+
+{style="narrow"}
+Type
+: `String`
+
+Default
+: `null`
+
+
+### purgeOldFiles
+{id="generatelexer-task-purgeoldfiles"}
+
+Purge old files from the target directory before generating the lexer.
+
+{style="narrow"}
+Type
+: `Boolean`
+
+Default
+: `false`
+
+
+## generateParser Task
+{id="generateparser-task"}
+
+The `generateParser` task generates a parser for the given grammar.
+The task is configured using common [`grammarKit`](#grammar-kit-extension) extension.
+
+
+### source
+{id="generateparser-task-source"}
+
+The source BNF file to generate the parser from.
+
+{style="narrow"}
+Required
+: `true`
+
+Type
+: `String`
+
+
+### targetRoot
+{id="generateparser-task-targetroot"}
+
+The path to the target directory for the generated parser.
+
+{style="narrow"}
+Type
+: `String`
+
+Default
+: `null`
+
+
+### pathToParser
+{id="generateparser-task-pathtoparser"}
+
+The location of the generated parser class, relative to the [`targetRoot`](#generateparser-task-targetroot).
+
+{style="narrow"}
+Required
+: `true`
+
+Type
+: `String`
+
+
+### pathToPsiRoot
+{id="generateparser-task-pathtopsiroot"}
+
+The location of the generated PSI files, relative to the [`targetRoot`](#generateparser-task-targetroot).
+
+{style="narrow"}
+Required
+: `true`
+
+Type
+: `String`
+
+
+### purgeOldFiles
+{id="generateparser-task-purgeoldfiles"}
+
+Purge old files from the target directory before generating the parser.
+
+{style="narrow"}
+Type
+: `Boolean`
+
+Default
+: `false`
+
+
+## Useful Resources
+
+* [Grammar-Kit](https://github.com/JetBrains/Grammar-Kit)
+* [IntelliJ-patched JFlex Sources](https://github.com/JetBrains/intellij-deps-jflex)
+* [IntelliJ-patched JFlex](https://cache-redirector.jetbrains.com/intellij-dependencies/org/jetbrains/intellij/deps/jflex/jflex/)
+
+### Usage Examples
+
+* [Perl5 plugin](https://github.com/Camelcade/Perl5-IDEA/blob/master/build.gradle)
+* [Rust plugin](https://github.com/intellij-rust/intellij-rust/blob/master/build.gradle.kts)
+* [Bamboo Soy plugin](https://github.com/google/bamboo-soy/blob/master/build.gradle)

topics/appendix/tools/tools_gradle_intellij_plugin_examples.md

@@ -15,7 +15,7 @@ As examples of using this plugin, you can also check out following projects:
 - [Rust plugin](https://github.com/intellij-rust/intellij-rust)
     - Uses the Gradle Kotlin DSL
     - Fully written in Kotlin
-    - Uses [Grammar Kit]
+    - Uses [Grammar-Kit]
 - [AWS CloudFormation plugin](https://github.com/shalupov/idea-cloudformation) and its [TeamCity build configuration](https://teamcity.jetbrains.com/project.html?projectId=IdeaAwsCloudFormation&tab=projectOverview)
 - [Bash plugin](https://github.com/jansorg/BashSupport) and its [TeamCity build configuration](https://teamcity.jetbrains.com/project.html?projectId=IntellijIdeaPlugins_BashSupport&tab=projectOverview)
 - [Perl5 plugin](https://github.com/hurricup/Perl5-IDEA) and its [Travis configuration file](https://github.com/hurricup/Perl5-IDEA/blob/master/.travis.yml)
@@ -40,7 +40,7 @@ As examples of using this plugin, you can also check out following projects:
 - [Minecraft Development](https://github.com/minecraft-dev/MinecraftDev) and its [TeamCity build configuration](https://ci.demonwav.com/viewType.html?buildTypeId=MinecraftDevIntelliJ_Build)
     - Uses the Gradle Kotlin DSL
     - Mixes Java, Kotlin, and Groovy code
-    - Uses [Grammar Kit]
+    - Uses [Grammar-Kit]
     - Uses a Kotlin version not bundled with IntelliJ IDEA
 - [Mainframer Integration](https://github.com/elpassion/mainframer-intellij-plugin)
     - Uses the Gradle Kotlin DSL
@@ -63,10 +63,10 @@ As examples of using this plugin, you can also check out following projects:
     - Uses the Gradle Kotlin DSL
     - Fully written in Kotlin
     - Uses other IntelliJ IDEA plugins as test dependencies
-    - Uses [Grammar Kit]
+    - Uses [Grammar-Kit]
     - Uses a Kotlin version not bundled with IntelliJ IDEA
 - [EduTools](https://github.com/JetBrains/educational-plugin)
     - Uses the Gradle Kotlin DSL
     - Mixes Java and Kotlin code
 
-[Grammar Kit]: https://github.com/JetBrains/Grammar-Kit
+[Grammar-Kit]: https://github.com/JetBrains/Grammar-Kit

topics/tutorials/custom_language_support/grammar_and_parser.md

@@ -54,7 +54,7 @@ private item_ ::= (property|COMMENT|CRLF)
 property ::= (KEY? SEPARATOR VALUE?) | KEY
 ```
 
-Please see [Grammar Kit](https://github.com/JetBrains/Grammar-Kit) documentation for more details on BNF syntax.
+Please see [Grammar-Kit](https://github.com/JetBrains/Grammar-Kit) documentation for more details on BNF syntax.
 
 The grammar defines the flexibility of the support for a language.
 The above grammar specifies that a property may have or may not have a key and value.
@@ -67,7 +67,7 @@ Note that the `SimpleTypes` class in the `elementTypeHolderClass` attribute abov
 Now that the grammar is defined, generate a parser with PSI classes via <control>Generate Parser Code</control> from the context menu on the <path>Simple.bnf</path> file.
 This step generates a parser and PSI elements in the <path>/src/main/gen</path> folder of the project.
 
-> Gradle plugin [gradle-grammar-kit-plugin](https://github.com/JetBrains/gradle-grammar-kit-plugin) can be used alternatively.
+> [Gradle Grammar-Kit Plugin](tools_gradle_grammar_kit_plugin.md) can be used alternatively.
 >
 {type="tip"}
 

topics/tutorials/custom_language_support/lexer_and_parser_definition.md

@@ -27,7 +27,7 @@ Choose the project root directory, for example <path>code_samples/simple_languag
 
 After that, the IDE generates the lexer under the <path>gen</path> directory, for example in <path>simple_language_plugin/src/main/gen/org/intellij/sdk/language/SimpleLexer</path>.
 
-> Gradle plugin [gradle-grammar-kit-plugin](https://github.com/JetBrains/gradle-grammar-kit-plugin) can be used alternatively.
+> [Gradle Grammar-Kit Plugin](tools_gradle_grammar_kit_plugin.md) can be used alternatively.
 >
 {type="tip"}