Skip to content

Commit

Permalink
docs: polish and format markdown documents (#19)
Browse files Browse the repository at this point in the history 
Signed-off-by: peefy <[email protected]>
  • Loading branch information
@Peefy
Peefy authored Dec 12, 2023
1 parent f0eef90 commit 8887db4
Show file tree
Hide file tree
Showing 3 changed files with 61 additions and 52 deletions.
24 changes: 12 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,51 +1,51 @@
# KCL Plugin for IntelliJ IDEA

The KCL IntelliJ IDEA plugin provides rich language support for the [KCL language](https://kusionstack.io/docs/reference/lang/).

The KCL IntelliJ IDEA plugin provides rich language support for the [KCL programming language](https://kcl-lang.io/).

## Quick Start

Welcome to KCL developing! We hope this plugin enhances your development experience with KCL.

- **Step 1.** Install kcl on your system. We highly recommend to [install the Kusion tools package](https://kusionstack.io/docs/user_docs/getting-started/install) which contains the KCL language support and other tools.
- **Step 2.** Install the KCL plugin for IntelliJ IDEA. Download the distribution from [here](distributions) and in IntelliJ IDEA, click Preference -> plugins -> install Plugin from Disk... -> select kcl-idea-plugin zip -> restart IDE. This plugin requires the IntelliJ IDEA 2020.2+
- **Step 3.** Open or create a KCL file and begin your KCL tour!
- **Step 1.** Install [KCL](https://kcl-lang.io/docs/user_docs/getting-started/install) on your system.
- **Step 2.** Install the KCL extension for IntelliJ IDEA. Download the distribution from [here](distributions) and in IntelliJ IDEA, click Preference -> plugins -> install Plugin from Disk... -> select `kcl-idea-plugin` zip -> restart IDE. This plugin requires the IntelliJ IDEA 2020.2+
- **Step 3.** Open or create a KCL file and begin your KCL tour!

<div style="text-align: center;"><img src="docs/img/how-to-install.gif" alt="IntelliJ KCL Plugin install"></div>

## Features

<!-- Plugin description -->
This extension provides coding assistance such as basic syntax highlight, IntelliSense such as auto complete, and some basic code navigation. Other useful features such as diagnostics and testing are in development.

This extension provides coding assistance such as basic syntax highlight, IntelliSense such as auto-complete, and some basic code navigation. Other useful features such as diagnostics and testing are in development.

<!-- Plugin description end -->

### Highlight

<div style="text-align: center;"><img src="docs/img/highlight.jpg" alt="highlight"></div>

### Code Formatting

Right click on the editor and select KCL Tools -> Format File to format current KCL file:
Right-click on the editor and select KCL Tools -> Format File to format the current KCL file:

<div style="text-align: center;"><img src="docs/img/format-file.png" alt="format file"></div>

Right click on the target directory in the project structure panel, select KCL Tools -> Format Directory to format all files under the selected folder:
Right-click on the target directory in the project structure panel, and select KCL Tools -> Format Directory to format all files under the selected folder:

<div style="text-align: center;"><img src="docs/img/format-directory.png" alt="format directory"></div>

Right click on the project name in the project structure panel, select KCL Tools -> Format Project to format all files in the project:
Right-click on the project name in the project structure panel, and select KCL Tools -> Format Project to format all files in the project:

<div style="text-align: center;"><img src="docs/img/format-project.png" alt="format project"></div>


## Ask for help

If the plugin isn't working as you expect, please reach out to us by filing an issue.


## Contributing

We are working actively on improving the KCL development on IntelliJ IDEA, and we welcome all kinds of contributions. You can refer to our [contribution guide](docs/CONTRIBUTING.md). It introduces how to build and run the extension locally.


## License

Apache License Version 2.0
36 changes: 21 additions & 15 deletions docs/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@

- the `intellij-kcl` plugin: This project
- Gradle Intellij Plugin: A Gradle IDE plugin that provides integration for compiling and building Gradle projects. This project uses Gradle for dependency management and building.
- Intellij Platform: A development platform provided by JetBrains that is built on top of IntelliJ IDEA. It offers a set of APIs and tools for extending IntelliJ functionality through plugins.
- Gradle plugins: Plugin dependencies declared in the project's Gradle configuration, used for extending and customizing the gradle build process. The current project relies on various Gradle plugins such as `java`, `org.jetbrains.kotlin.jvm`, `org.jetbrains.intellij`, `org.jetbrains.changelog`, etc.
- Intellij Platform: A development platform provided by JetBrains that is built on top of IntelliJ IDEA. It offers a set of APIs and tools for extending IntelliJ functionality through plugins.
- Gradle plugins: Plugin dependencies declared in the project's Gradle configuration, used for extending and customizing the gradle build process. The current project relies on various Gradle plugins such as `java`, `org.jetbrains.kotlin.jvm`, `org.jetbrains.intellij`, `org.jetbrains.changelog`, etc.
- the `Target` IntelliJ version: Named in the format of `yyyy.m (e.g., 2023.2)` or `yym.a (e.g., 232.3)`, this refers to the target platform version(s) that the plugin should support. It needs to be declared in the plugin project.

## Project Structure

For details, please see https://plugins.jetbrains.com/docs/intellij/creating-plugin-project.html#components-of-a-wizard-generated-gradle-intellij-platform-plugin
For details, please see [https://plugins.jetbrains.com/docs/intellij/creating-plugin-project.html#components-of-a-wizard-generated-gradle-intellij-platform-plugin](https://plugins.jetbrains.com/docs/intellij/creating-plugin-project.html#components-of-a-wizard-generated-gradle-intellij-platform-plugin)

```markdown
intellij-kcl
Expand All @@ -36,6 +36,7 @@ intellij-kcl
├── gradlew.bat
└── settings.gradle.kts # Project metadata, such as the project name.
```

## Build Guide

### Build
Expand Down Expand Up @@ -74,12 +75,11 @@ $ ./gradlew runIde
This plugin is built on top of the [IntelliJ Platform SDK](https://plugins.jetbrains.com/docs/intellij/intellij-platform.html). When updating the Intellij-based IDE product, it is necessary to ensure the compatibility between the plugin and the IDE:

- In the `build.gradle.kts` file, set the `intellij.version` to the version of the IntelliJ Platform SDK used for plugin build, and declare the lower bound and upper bound versions compatible with the IntelliJ product through `tasks.patchPluginXml.sinceBuild` and `tasks.patchPluginXml.untilBuild`.

- Regularly check the compatibility between the version of the IDE and the plugin: when a new version of the intellij-based IDE is released, set `pluginUntilBuild` in the `gradle.properties` file to the version number of the new version (for example, 2023.1 for version number 231), and verify compatibility by running `./gradlew verifyPluginConfiguration` or trigger the `verifyPluginConfiguration` task in the IntelliJ IDEA > gradle toolbar.

### Publish Plugin

To register and publish to the plugin marketplace, see: https://plugins.jetbrains.com/docs/intellij/plugin-signing.html#provide-secrets-to-ide https://plugins.jetbrains.com/docs/intellij/publishing-plugin.html
To register and publish to the plugin marketplace, see: [https://plugins.jetbrains.com/docs/intellij/plugin-signing.html#provide-secrets-to-ide](https://plugins.jetbrains.com/docs/intellij/plugin-signing.html#provide-secrets-to-ide) [https://plugins.jetbrains.com/docs/intellij/publishing-plugin.html](https://plugins.jetbrains.com/docs/intellij/publishing-plugin.html)

## Lexer & Parser Generation

Expand All @@ -103,28 +103,33 @@ To register and publish to the plugin marketplace, see: https://plugins.jetbrain
The plugin should be compatible across different IntelliJ Platform versions unless for special reasons. However, there may be some API changes that are not backward compatible between major IntelliJ versions.

For version differences, please refer to:
- https://plugins.jetbrains.com/docs/intellij/api-changes-list.html
- https://plugins.jetbrains.com/docs/intellij/api-notable.html

And we can use the predefined Gradle task (`verifyPluginConfiguration`) to verify the compatibility between the plugin and the platform: https://plugins.jetbrains.com/docs/intellij/verifying-plugin-compatibility.html
- [https://plugins.jetbrains.com/docs/intellij/api-changes-list.html](https://plugins.jetbrains.com/docs/intellij/api-changes-list.html)
- [https://plugins.jetbrains.com/docs/intellij/api-notable.html](https://plugins.jetbrains.com/docs/intellij/api-notable.html)

And we can use the predefined Gradle task (`verifyPluginConfiguration`) to verify the compatibility between the plugin and the platform: [https://plugins.jetbrains.com/docs/intellij/verifying-plugin-compatibility.html](https://plugins.jetbrains.com/docs/intellij/verifying-plugin-compatibility.html)

### Gradle Intellij Plugin Version Compatibility

It is recommended to always use the latest version. Here are some notable compatibility requirements:

- For IntelliJ 2022.3+, Gradle IntelliJ Plugin version 1.10.1+ is required.
- Note that starting from IntelliJ 2023.3+, the Gradle plugin is no longer built-in and needs to be installed separately.

### JDK Version Compatibility

For different target intellij platform versions, we'll need different Java Runtime versions:

- 2020.3 and before: Java 11
- 2022.2 and after: Java 17
For the compatibility table, please refer to: https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html#platformVersions

For the compatibility table, please refer to: [https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html#platformVersions](https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html#platformVersions)

#### Which target Platform Versions to maintain

The plugin needs to target different IntelliJ Platform versions. If necessary, separate branches can be created for different IntelliJ major versions (e.g., starting from 2023.2+, supporting LSP, we maintain the LSP-related plugin code in a separate branch).
Which versions to focus on maintaining can be decided based on the distribution of user-side versions provided by Jetbrains: https://plugins.jetbrains.com/docs/marketplace/product-versions-in-use-statistics.html

Which versions to focus on maintaining can be decided based on the distribution of user-side versions provided by Jetbrains: [https://plugins.jetbrains.com/docs/marketplace/product-versions-in-use-statistics.html](https://plugins.jetbrains.com/docs/marketplace/product-versions-in-use-statistics.html)

### Build Failed: Download Timeout

Expand All @@ -135,8 +140,9 @@ The first time you run ./gradlew build can be quite time-consuming (around 5-15
When a test class is deleted and rebuilt, IntelliJ IDEA still attempts to run the deleted test class. You need to clear the cache.

## References
- Custom Language Plugin Development Guide: https://plugins.jetbrains.com/docs/intellij/custom-language-support.html
- Plugin Testing Guide: https://jetbrains.org/intellij/sdk/docs/tutorials/writing_tests_for_plugins.html
- Plugin Project Configuration: https://plugins.jetbrains.com/docs/intellij/configuring-plugin-project.html
- JDK and IntelliJ Platform SDK Compatibility: https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html
- Find all plugin repositories that implement a certain extension point: https://plugins.jetbrains.com/intellij-platform-explorer/extensions?extensions=com.intellij.lineIndentProvider

- Custom Language Plugin Development Guide: [https://plugins.jetbrains.com/docs/intellij/custom-language-support.html](https://plugins.jetbrains.com/docs/intellij/custom-language-support.html)
- Plugin Testing Guide: [https://jetbrains.org/intellij/sdk/docs/tutorials/writing_tests_for_plugins.html](https://jetbrains.org/intellij/sdk/docs/tutorials/writing_tests_for_plugins.html)
- Plugin Project Configuration: [https://plugins.jetbrains.com/docs/intellij/configuring-plugin-project.html](https://plugins.jetbrains.com/docs/intellij/configuring-plugin-project.html)
- JDK and IntelliJ Platform SDK Compatibility: [https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html](https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html)
- Find all plugin repositories that implement a certain extension point: [https://plugins.jetbrains.com/intellij-platform-explorer/extensions?extensions=com.intellij.lineIndentProvider](https://plugins.jetbrains.com/intellij-platform-explorer/extensions?extensions=com.intellij.lineIndentProvider)
Loading

0 comments on commit 8887db4

Please sign in to comment.