hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-30 18:27:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

IJSDK-739

Browse Source
This commit is contained in:
JohnHake 2020-02-07 16:54:11 -08:00
parent 54d822dd25
commit 77c97c2c08
2 changed files with 55 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
intro/sdk_code_guidelines.md
View File

@ -75,16 +75,18 @@ code_samples/
src/
main/
java/
org.intellij.sdk.foo/
icons/
FooBasicsIcons.java
SdkIcons.java # The standard SDK icon class
resources/
icons/
sdk.svg # The standard SDK icon for menus, etc.
sdk_16.svg # The standard SDK icon for menus, etc.
META-INF/
plugin.xml # The plugin configuration file
pluginIcon.svg # The standard SDK plugin icon
test/ # Omit if there are no tests
java/
org.intellij.sdk.foo/
resources/
build.gradle
gradlew
@ -104,21 +106,17 @@ Comments in SDK code sample `build.gradle` files should only draw attention to t
For SDK code samples, a few alterations are needed to the default build.gradle file produced by the plugin wizard:
* Maintain the Gradle properties `version` (`project.version`) and `group` (`project.group`).
See the [Plugin Gradle Properties](/tutorials/build_system/prerequisites.md#plugin-gradle-properties-and-plugin-configuration-file-elements) section for how these Gradle properties relate to the elements in `plugin.xml`.
* Add the following statements to the [Setup DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#setup-dsl) (`intellij{}`) section:
* Add the following statement to the [Setup DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#setup-dsl) (`intellij{}`) section:
```groovy
// Prevents patching <idea-version> attributes in plugin.xml
updateSinceUntilBuild = false
// Define a shared sandbox directory for running code sample plugins within an IDE.
sandboxDirectory = file("${project.projectDir}/../_idea-sandbox")
```
* Remove the [Patching DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#patching-dsl) (`patchPluginXml{}`) section.
It is not needed in SDK samples.
* Add the `javadoc` task to build documentation for the code sample:
* Add the following statement to the [Patching DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#patching-dsl) (`patchPluginXml{}`) section:
```groovy
// Force javadoc rebuild before jar is built
jar.dependsOn javadoc
```
// Patches <version> value in plugin.xml
version = project.version
```
## plugin.xml Conventions
A consistent structure for the [`plugin.xml`](/basics/plugin_structure/plugin_configuration_file.md) configuration file of an SDK code sample is important because we want to draw attention to the unique parts of the file for a plugin.
Inconsistent element order is visually noisy.
@ -135,7 +133,7 @@ The sequence of elements in an SDK code sample `plugin.xml` file is:
* FIX corresponds to changes that fix problems without significant refactoring.
* `<idea-version>` Set the attributes:
* `since-build` attribute to the earliest compatible build number of the IntelliJ Platform.
The default for SDK samples is "173".
The default for SDK samples is "193".
* `until-build` Omit this attribute for new sample plugins.
SDK code samples are reviewed before every major release (20XX.1) to ensure compatibility with the latest IntelliJ Platform.
Add this attribute if a plugin sample is deprecated with a release of the IntelliJ Platform.

62
intro/sdk_style.md
View File

@ -102,38 +102,61 @@ See the [Jekyll site](https://jekyllrb.com/docs/liquid/) for more details.
Consistent text styles are used to standardize references and keywords:
* Menu paths are formatted as bold with pipe characters separating each level: \*\*Preferences \\\| Editor\*\* (**Preferences \| Editor**)
* Keywords and quotations are formatted as italic: \_UI Theme\_ (_UI Theme_)
* File names and paths, in-paragraph code fragments, and language keywords are formatted as code: \`interface\` (`interface`),
* File names and paths, and language keywords are formatted as code: \`interface\` (`interface`)
See [Syntax Highlighting](#syntax-highlighting) for more details about representing in-paragraph code fragments.
* File formats are shown as all capital letters: PNG and XML.
* File name extensions are not capitalized when part of a full file name, path, or URL: `filename.ext`.
* Represent keyboard shortcuts with HTML elements: `press <kbd>Alt</kbd>+<kbd>Insert</kbd>` becomes "press <kbd>Alt</kbd>+<kbd>Insert</kbd>"
* [Links](#links) have a particular format depending on the type of link.
### Terminology
Consistent terminology helps the reader grasp new concepts more quickly:
* The open source code in the GitHub repository `intellij-community` is known as the _IntelliJ Platform_.
Use the full phrase in SDK documentation.
* IDEs based on the IntelliJ Platform are described as _IntelliJ Platform-based IDEs_.
Once that term is used on a page, after that authors may use IDEs
* When referring to JetBrains products always use the full name such as _IntelliJ IDEA_.
Once that term is used on a page, authors may use _IDEs_
* When referring to JetBrains products always use the full name such as _IntelliJ IDEA Ultimate Edition_.
However, only use product names when extensibility or functionality is particular to a product.
### Syntax highlighting
Source code can be represented by using [GitHub Flavoured Markdown](https://help.github.com/articles/github-flavored-markdown/) code fences, which are three backticks:
### Syntax Highlighting
In-paragraph code fragments and IntelliJ Platform APIs are formatted according to these rules:
* Avoid using qualifiers like "`foo` interface" or "`foo` abstract class."
Just refer to `foo`.
* Use the FQN when first introducing an extension point on a page.
Rather than `stubIndex`, introduce `com.intellij.stubindex`.
Subsequent mentions on the page can be `stubIndex`.
Exception: the FQN is not used when an extension point is introduced in an upsource [link](#links).
* Method names always use empty parentheses: `bar()`.
Method names are prefixed with the class/interface name when needed for clarity: `foo.bar()`.
```
// Source code goes here...
```
Source code can be represented by using [GitHub Flavoured Markdown](https://help.github.com/articles/github-flavored-markdown/) code fences, which are three backticks:
Syntax highlighting can be applied by specifying the language after the first set of ticks:
```
// Source code goes here...
```
```csharp
// Some C# code
```
Syntax highlighting can be applied by specifying the language after the first set of ticks:
```java
// Some Java code
```
```csharp
// Some C# code
```
Here is the list of [supported languages](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers), and also [Kotlin](https://kotlinlang.org), of course.
```java
// Some Java code
```
Here is the list of [supported languages](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers), and also [Kotlin](https://kotlinlang.org), of course.
Whole files can be imported on a page.
The advantage is the code can come from code_samples, so it will be live code that isn't silently stale.
The disadvantage is the file may contain a large class, too large for the documentation page to be effective.
```java
// include statement
```
In any case, please keep code samples concise and avoid any unnecessary "surrounding" code or import statements.
Please keep code samples concise and avoid any unnecessary "surrounding" code or import statements.
<!-- //TODO: Not currently supported by rouge, or by the site's CSS
@ -166,7 +189,10 @@ Links to files in the IntelliJ Platform (`intellij-community`) repository use `u
The `upsource:///` URI effectively points to the root of the `intellij-community` repository.
* `[README.md](upsource:///README.md)` for links to general files in the repository.
* `[`\`AnAction\``](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)` for links to source code files for interfaces and classes.
Note the use of \`\` characters surrounding the class name in the link.
* Note the use of \`\` characters surrounding the class name in the link.
* When linking to an API in this manner the FQN isn't necessary in the link.
* Be judicious when using such links.
Generally only one link is needed for a given file on a documentation page.
General links have one of the following formats:
* `[External site](https://example.org)` links to an external site.