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

Merge pull request #165 from JohnHake/IJSDK-600

Browse Source 
IJSDK-600 - Add SDK code and doc style guides
This commit is contained in:
John Hake 2019-04-25 10:35:00 -07:00 committed by GitHub
commit 61e124bbfa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 484 additions and 224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

278
CONTRIBUTING.md
View File

@ -1,46 +1,30 @@
---
title: Contributing
title: Contributing to the IntelliJ Platform SDK
---
Thanks for contributing! Here are a few useful things to know before submitting your Pull Request.
This document describes our contribution guidelines for the open source IntelliJ Platform SDK documentation and sample code.
Before you begin contributing content to the SDK, please read this page thoroughly as well as the [Code of Conduct](/CODE_OF_CONDUCT.md) and [License](https://github.com/JetBrains/intellij-sdk-docs/blob/master/LICENSE.txt) documents.
For information about contributing to the IntelliJ Platform itself, please visit [Contributing to the IntelliJ Platform](/basics/platform_contributions.md).
* Licensing - see [LICENSE.txt](LICENSE.txt)
* [Contributing to the IntelliJ Platform](#contributing-to-the-intellij-platform)
* [Setting up your environment](#setting-up-your-environment)
* [Developing with Docker](#developing-with-docker)
* [Developing locally](#developing-locally)
* [Markup](#markup)
* [_SUMMARY.md](#summarymd)
* [Redirects](#redirects)
* [Table of contents](#table-of-contents)
* [Liquid tags and filters](#liquid-tags-and-filters)
* [Syntax highlighting](#syntax-highlighting)
* [Tables](#tables)
* [Links](#links)
* [Callouts](#notes-and-callouts)
* [Images](#images)
* Style guide
* [A word on submodules](#a-word-on-submodules)
## Contributing to the IntelliJ Platform
This document describes our contribution guidelines for the IntelliJ SDK Docs. For information about contributing to the IntelliJ Platform, please visit [Contributing to the IntelliJ Platform](/basics/platform_contributions.md).
## Setting up your environment
Here are some useful things to know before authoring SDK content and submitting your Pull Request.
* Dummy list item
{:toc}
## Setting Up the Documentation Build Environment
This site runs via [Jekyll](https://jekyllrb.com), which is a popular static site generator, written in Ruby. It can be hosted locally to ensure that any changes are correct. Once set up, running the site is as easy as calling `rake preview`.
Alternatively, the site can also be hosted in a [Docker container](https://www.docker.com). On Mac and Windows, this means the site is hosted in a virtual machine. Docker maintains this container, building it based on the instructions in the [`Dockerfile`](Dockerfile). All dependencies (Ruby, etc.) are automatically installed when building the image, which reduces the manual configuration steps. The Docker image is also used to build the [published site](https://www.jetbrains.org/intellij/sdk/docs/index.html), so it is a known working environment.
### Developing with Docker
### Developing Documentation with Docker
Follow these steps to work with Docker:
* Firstly, install Docker, using the [Docker Toolbox](https://www.docker.com/docker-toolbox).
* On Windows and Mac, start the Docker host virtual machine (start the "Docker Quickstart terminal" or run "Kitematic". See the Getting Started guides on [docker.com](https://www.docker.com) for more details).
* On Windows and Mac, start the Docker host virtual machine (start the "Docker Quickstart terminal" or run "Kitematic." See the Getting Started guides on [docker.com](https://www.docker.com) for more details).
* Clone the [`intellij-sdk-docs`](https://github.com/JetBrains/intellij-sdk-docs) repo to the local machine, and [initialise the `sdkdocs-template` submodule](#a-word-on-submodules).
* Change the current directory to the parent directory of the git repo.
* Run `docker build -t intellij-sdk-docs .`. This will build the docker image from the current folder, and give it the tag `intellij-sdk-docs`.
* Run `docker build -t intellij-sdk-docs .` to build the docker image from the current folder, and give it the tag `intellij-sdk-docs`.
* Note that this must be run from a command prompt that has the various `DOCKER_*` environment variables set up, such as the Docker Quickstart Terminal.
* Run `docker run -p 4000:4000 -v $PWD:/usr/src/app intellij-sdk-docs`. This command will:
* Start the docker container called `intellij-sdk-docs`.
@ -52,33 +36,35 @@ Follow these steps to work with Docker:
>
> Alternatively, modify the virtual machine's settings to automatically forward port 4000 to `localhost`. See this [blog post](https://acaird.github.io/computers/2014/11/16/docker-virtualbox-host-networking) for more details.
* Mount the current directory (`$PWD` is a Unix style environment variable. You can use `%CD%` on Windows, or specify the full path) as `/usr/src/app` inside the docker container. This means the docker image will see the `intellij-sdk-docs` repo as the folder `/usr/src/app`.
* Mount the current directory (`$PWD` is a Unix style environment variable. You can use `%CD%` on Windows, or specify the full path) as `/usr/src/app` inside the docker container. The docker image will see the `intellij-sdk-docs` repo as the folder `/usr/src/app`.
> **NOTE** If running on Windows in an msys bash script (e.g. the "Docker Quickstart terminal"), the path to the local folder needs to be properly escaped, or the msys environment will translate the paths to standard Windows path, and you will see an error such as `invalid value "C:\\Users\\...;C:\\Program Files\\Git\\usr\\src\\app" for flag -v`. To fix this, prefix the full path with double slashes, e.g. `-v //c/Users/...`, or `docker run -p 4000:4000 -v /$PWD:/usr/src/app intellij-sdk-docs` (note the leading slash before `$PWD`).
> **NOTE** If running on Windows in an MSYS bash script (e.g. the "Docker Quickstart terminal"), the path to the local folder needs to be properly escaped, or the MSYS environment will translate the paths to standard Windows path, and causing an error such as `invalid value "C:\\Users\\...;C:\\Program Files\\Git\\usr\\src\\app" for flag -v`. To fix this problem, prefix the full path with double slashes, e.g. `-v //c/Users/...`, or `docker run -p 4000:4000 -v /$PWD:/usr/src/app intellij-sdk-docs` (note the leading slash before `$PWD`).
* Run the commands specific in the Dockerfile's `CMD` instruction, which runs both `rake bootstrap`, which ensures all of the prerequisites are installed, and `rake preview`, which builds the site and starts to host it.
* Finally, you can access the newly created site by visiting [http://localhost:4000/intellij/sdk/docs/](http://localhost:4000/intellij/sdk/docs/), or by using the IP address of the docker client virtual machine (see note above).
* Run the commands in the Dockerfile's `CMD` instruction to execute:
* `rake bootstrap`, which ensures all of the prerequisites are installed,
* `rake preview`, which builds the site and starts to host it.
* Finally, you can access the newly created site by visiting [http://localhost:4000/intellij/sdk/docs/](http://localhost:4000/intellij/sdk/docs/), or by using the IP address of the docker client virtual machine (see the note above).
### Developing locally
### Developing Documentation Locally
To build the documentation site, you will need:
To build the documentation site, you need:
* Ruby 2 - Jekyll is a Ruby application.
* Ruby 2 DevKit (for Windows) - Some of Jekyll's dependencies need to be compiled, and require the DevKit to be installed.
* `gem install bundler` - the site uses [Bundler](https://bundler.io) to manage gem dependencies within the repo, rather than globally installing to the local operating system. Run this command to install the Bundler toolset globally.
**OS X**
#### macOS
OS X comes with Ruby already installed. The only steps required are:
macOS comes with Ruby already installed. The only steps required are:
* `gem install bundler`
**Windows**
#### Windows
* Install [Ruby 2](https://rubyinstaller.org) and the [Ruby 2 DevKit](http://rubyinstaller.org/downloads/) (one of the gems needs to build a native component)
* After installing the DevKit, make sure to edit the `config.yml` file to point to the Ruby installation
This is made easier if you use [Chocolatey](https://chocolatey.org), a package manager for Windows:
This installation is easier if you use [Chocolatey](https://chocolatey.org), a package manager for Windows:
* `choco install ruby`
* `choco install ruby2.devkit`
@ -88,202 +74,54 @@ This is made easier if you use [Chocolatey](https://chocolatey.org), a package m
> **NOTE** Before running the `rake bootstrap` step listed below, please run the `devkitvars.bat` file from the DevKit. E.g. `C:\tools\DevKit\devkitvars.bat`
### Bootstrapping the environment
### Bootstrapping the Documentation Build Environment
1. Ensure Bundler is installed - `gem install bundler`
1. Ensure Bundler is installed - `gem install bundler`.
2. On Windows, ensure the `devkitvars.bat` file has been run in the current command prompt (e.g. `c:\tools\DevKit\devkitvars.bat`).
3. Clone the documentation site.
4. Initialise and update the `sdkdocs-template` submodule - `git submodule init` and `git submodule update`
4. Initialize and update the `sdkdocs-template` submodule - `git submodule init` and `git submodule update`
5. `rake bootstrap` - this uses Bundler to download all required gems.
6. `rake preview` - this will build the site, and host it in a local webserver.
6. `rake preview` - this will build the site, and host it in a local webserver.
### Building and previewing the site
### Building and Previewing the Site
To build and test the site, simply run `rake preview`. This will build the site and host it, using the config provided. The URL of the hosted site is displayed on the screen and depends on the `baseurl` field defined in `_config.yml`.
To build and test the site, run `rake preview`. This will build the site and host it, using the config provided. The URL of the hosted site is displayed on the screen and depends on the `baseurl` field defined in `_config.yml`.
> **NOTE** You must use `localhost` as hostname, otherwise fonts will fail to load.
> **NOTE** You must use `localhost` as hostname, _NOT_ 0.0.0.0, otherwise fonts fail to load.
## Markup
## Documentation Repository Submodules
The `sdkdocs-template` directory is actually a Git submodule, and it contains a submodule to the private `webhelp-template` repository.
The `sdkdocs-template` repository contains build scripts and compiled and minified JS and CSS that allow the site to run.
The private `webhelp-template` repository contains the code to build the JS and CSS.
It is currently closed source, but the plan is to make it open source at some point, in which case it is likely the two repositories will be merged.
By default, when building the site, all files are copied to the destination `_site` folder. Some files are excluded in the `_config.yml` and `sdkdocs-template/jekyll/_config-defaults.yml` files. The documentation files themselves are [Markdown](https://daringfireball.net/projects/markdown/) files (`.md`) that get automatically converted to HTML when the site is built.
After cloning, a submodule needs to be initialized and updated:
However, only markdown files beginning with a [YAML](https://yaml.org) header are converted. If the markdown file doesn't contain a header, it won't be converted. In other words, to convert a `.md` file to HTML, it should look like this:
```md
---
---
# Introduction
Lorem ipsum...
```sh
git submodule init
git submodule update
```
The two lines at the top of the file are the markers of the YAML "front matter". Fields can be added in between these markers, and are used when generating the HTML. Typically, this header will be empty, although it is required by Jekyll (if omitted, the file isn't converted).
Initialization creates a `.gitmodules` file, register a submodule in the `sdkdocs-template` folder and check out the files.
Note that when a repo is added as a submodule, it doesn't get a `.git` folder, but instead gets a `.git` file that points to the actual location of the `.git` folder.
The YAML header can contain data that is used when generating the site. For example, the page title can be specified as a simple piece of markdown - `# Title`, or it can be specified in the YAML, and the page template will display it appropriately:
A submodule can be updated using normal git commands such as `git pull`.
It can be switched to a different branch using `git checkout`, and any changes to the currently checked out revision need to be committed back into the main repository using git commands.
A submodule is initially cloned at a specific revision, and not as part of a branch.update
```md
---
title: The Title Of The Page
---
Lorem ipsum...
```
The YAML header can also include [redirect](#redirects) information.
### _SUMMARY.md
The table of contents for the site is displayed in the tree view on the left-hand side of the site, and it is generated from the `_SUMMARY.md` file. It is a simple markdown list, with each item in the list being a link to another markdown page, either in the root folder, or sub-folders. The list can have nested items, which will be displayed as child items in the table of contents.
```md
# Summary
* [Introduction](README.md)
* [About This Guide](Intro/About.md)
* [Key Topics](Intro/KeyTopics.md)
```
The contents can be split into "parts" by separating the list into several lists, each new list starting with a level 2 heading (`##`).
```md
# Summary
* [Introduction](README.md)
* [About This Guide](Intro/About.md)
* [Key Topics](Intro/KeyTopics.md)
## Part I - Extending the Platform
* [Getting Started](Docs/GettingStarted.md)
* ...
```
If a node doesn't have a link, but is just plain text, it will still appear in the table of contents but will be greyed out and not clickable. It acts as a placeholder for a documentation item. This is useful to keep track of what should be documented, but hasn't yet, and can be useful to show readers that the topic exists, but isn't yet documented (Pull Requests always welcome!).
### Redirects
The documentation site is set up to include the [jekyll-redirect-from](https://github.com/jekyll/jekyll-redirect-from) plugin, which will generate "dummy" pages that automatically redirect to a given page. For example, to specify that the `index.html` page will be generated to redirect to `README.md`, the `README.md` file should include the following in the YAML header:
```md
---
redirect_from:
- /index.html
---
# Introduction
Lorem ipsum...
```
This will create an `index.html` file that will automatically redirect to the generated `README.html` file. This is very useful to allow the site URL to automatically show the `README.html` file - `http://localhost:4001/foo-test/` will try to load `index.html`, which will automatically redirect to `README.html`.
It is also useful to redirect when renaming or moving files. Multiple redirects can be added to the YAML header.
### Table of contents
The site is configured to use the [Kramdown Markdown converter](http://kramdown.gettalong.org), which adds some extra features over traditional markdown, such as "attribute lists", which can apply attributes to the generated elements.
One useful attribute is `{:toc}`, which can be applied to a list item, which will get replaced with a list of links to header items. E.g. the following list item will be replaced by links to all of the header items in the page:
```md
* Dummy list item
{:toc}
```
Further Kramdown features are described on the [converter page](https://kramdown.gettalong.org/converter/html.html), and attribute lists are described on the [syntax page](http://kramdown.gettalong.org/syntax.html). Note that source code formatting is configured to use [GitHub Flavoured Mardown](https://help.github.com/articles/github-flavored-markdown/) and "code fences", see below.
### Liquid tags and filters
Jekyll uses the [Liquid](https://shopify.github.io/liquid/) templating language to process files. This means standard Liquid tags and filters are available. There should be little need to use them, however, as the Markdown format is already quite rich. See the [Jekyll site](http://jekyllrb.com/docs/templates/) for more details.
### 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:
```
// Source code goes here...
```
Syntax highlighting can be applied by specifying the language after the first set of ticks:
```csharp
// Some C# code
```
```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).
Please keep code samples concise and avoid any unnecessary "surrounding" code or import statements.
<!-- Not currently supported by rouge, or by the site's CSS
The site is also configured to highlight a range of files in the source code, by specifying `{start-end}` which is the start and end line of the highlighting:
```java{2-3}
// Not highlighted
// Highlighted
// Highlighted
// Not highlighted
```
-->
### Tables
The Kramdown parser also supports tables. The syntax is to use the pipe (`|`) and minus symbols:
```md
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Blah | Blah | Blah |
```
### Links
Links are handled as normal markdown links and can be linked to external sites, pages within the sites, or headings in the sites. When a Markdown header is converted to an HTML header, it is assigned an ID, so it can be linked, e.g. `## Introduction` will get the ID of `introduction`, and can be linked either in the same page `[click here](#introduction)` or cross-page `[click here](page.html#introduction)`. The anchor name will be all lower case, and spaces are replaced with `-`, e.g. `## Page setup` becomes `#page-setup`.
* `[External site](http://example.org)` will link to an external site
* `[Other page in current directory](Page2.md)` will link to a page in the same directory as the current page. Note that the extension is `.md`, NOT `.html`.
* `[Page in another folder](/Folder2/Page2.md)` will link to a page in another folder. Note that the URL is navigating from root - this works even if the site is hosted in a sub-folder (e.g. this link will work for `http://localhost:4000/devguide/Folder2/Page2.html`). Relative links will also work (`../Folder2/Page2.md`).
* `[Link to section on another page](Page2.md#another-section)` will link to a heading on another page. The ID of the heading is generated by making the text lowercase and replacing spaces with `-`.
* `[Link to section on current page](#another-section)` will link to a heading on the current page.
### Notes and callouts
Notes and callouts can be specified using the blockquote syntax. The converter will look at the first following word to see if it is bold. If so, it will apply that as a callout style. For example:
> **NOTE** This is a note
Will be displayed as a callout, styled as a "note". The other styles available for callouts are "note", "warning", "tip" and "todo".
### Images
Images can be included by adding the file directly to the repository and adding a link to the image like so:
![Alt text](path-to-img.png)
Please, downscale screenshots made at high resolution.
![Alt text](path-to-img.png){:width="42px"}
## A word on submodules
The `sdkdocs-template` repo is added as a submodule, and it also contains a submodule to the private `webhelp-template` repo. The `sdkdocs-template` repo contains build time scripts and compiled and minified JS and CSS that allow the site to run. The private `webhelp-template` repo contains the code to build the JS and CSS. It is currently closed source, but the plan is to make it open source at some point, in which case, it is likely the two repos will be merged.
After cloning, a submodule needs to be initialised and updated:
```
git submodule init
git submodule update
```
This will create a `.gitmodules` file, register a submodule in the `sdkdocs-template` folder, and check out the files. (Note that when a repo is added as a submodule, it doesn't get a `.git` folder, but instead gets a `.git` file that points to the location of the `.git` folder.
A submodule can be updated using normal git commands such as `git pull`. It can be switched to a different branch using `git checkout`, and any changes to the currently checked out revision need to be committed back into the main repo, as normal git commands. It is initially cloned at a specific revision, and not as part of a branch.update
If changes are made to the submodule, they should be made on a branch to a clone, and a Pull Request sent. Changes can be made and committed, and the hosting repo will need to commit a pointer to the current version of the submodule.
If changes are made to the submodule, they should be made on a branch to a clone, and a Pull Request sent.
Changes can be made and committed, and the hosting repository will need to commit a pointer to the current version of the submodule.
If there are any problems with the `sdkdocs-template`, please [raise an issue](https://github.com/JetBrains/sdkdocs-template/issues).
## Creating IntelliJ Platform SDK Content
Content contributions to the IntelliJ Platform SDK are welcome.
Please download or clone the open source SDK project from [GitHub](https://github.com/JetBrains/intellij-sdk-docs), make additions or changes, and submit a pull request.
Before creating or altering content, please consult these guides:
* [SDK Documentation Style Guide](intro/sdk_style.md).
This guide describes documentation conventions in terms of Markdown syntax.
Always test documentation changes using a [preview](#building-and-previewing-the-site) of the site.
* [SDK Code Sample Guidelines](intro/sdk_code_guidelines.md).
Conventions for code sample organization, project settings, and naming conventions are described in this document.
Always test code changes by building and testing the SDK code sample.

8
_SUMMARY.md
View File

@ -3,10 +3,12 @@
* [Introduction](welcome.md)
* [The IntelliJ Platform](intro/intellij_platform.md)
* [Contributing to the IntelliJ Platform](basics/platform_contributions.md)
* [IntelliJ Coding Guidelines](basics/intellij_coding_guidelines.md)
* [About this Guide](intro/about.md)
* [IntelliJ Platform Coding Guidelines](basics/intellij_coding_guidelines.md)
* [The IntelliJ Platform SDK](intro/about.md)
* [Key Topics](intro/key_topics.md)
* [Contributing](CONTRIBUTING.md)
* [Contributing to the SDK](CONTRIBUTING.md)
* [SDK Docs Style Guide](intro/sdk_style.md)
* [SDK Code Sample Guidelines](intro/sdk_code_guidelines.md)
* [Code of Conduct](CODE_OF_CONDUCT.md)
* [Getting Help](intro/getting_help.md)

2
basics/intellij_coding_guidelines.md
View File

@ -1,5 +1,5 @@
---
title: IntelliJ Coding Guidelines
title: IntelliJ Platform Coding Guidelines
---
If you are writing code that you would like to contribute to the IntelliJ Platform (either as a patch or as a plugin), following these guidelines will make it easier for the JetBrains development team to review and accept your changes.

152
intro/sdk_code_guidelines.md Normal file
View File

@ -0,0 +1,152 @@
---
title: Guidelines for Creating IntelliJ Platform SDK Code Samples
---
This document describes the coding guidelines used for authoring open source IntelliJ Platform SDK code samples.
Before you begin, please read this page thoroughly as well as the [Code of Conduct](/CODE_OF_CONDUCT.md) and [License](https://github.com/JetBrains/intellij-sdk-docs/blob/master/LICENSE.txt) documents.
For information about contributing to the IntelliJ Platform itself visit [Contributing to the IntelliJ Platform](/basics/platform_contributions.md).
## Objectives
Keep the following considerations in mind while authoring an SDK code sample:
* The purpose of an SDK sample is to demonstrate an implementation pattern to build on top of subsystems and components of the IntelliJ Platform.
* SDK code samples are instructional code, intended to teach.
* Instructional code differs from production code in some key aspects:
* Sacrifice some robustness in the interest of simplicity and brevity.
Use error checking where it is necessary to make a point about an implementation pitfall.
* Keep implementations as simple as possible, but use the full features of the IntelliJ Platform, Java language, and libraries.
* Use meaningful names for interfaces, classes, fields, methods, and extension points.
* Write instructional JavaDoc comments.
* Code samples replace lots of documentation.
* Aim for two levels of SDK samples:
* A _basic_ sample is focused on a particular subject by demonstrating a limited area of the IntelliJ Platform.
It should show all the components and architecture but ultimately accomplish something elementary.
For example, demonstrate persistence by storing only a `String`.
* An _advanced_ sample demonstrates how different parts of the IntelliJ Platform integrate and work together.
For example, combining inspections or intentions with non-trivial PsiTree manipulation.
Ultimately, the goal is to provide developers with roadmaps for implementing functionality in an IntelliJ Platform-based plugin.
Each roadmap should contain:
* Pointers to SDK documentation about the IntelliJ Platform APIs needed to implement the functionality.
* Pointers to relevant _basic_ SDK sample plugins.
* Pointers to relevant _advanced_ SDK sample plugins.
## Naming Conventions for SDK Plugins
For _basic_ samples, the naming convention is focused on the IntelliJ Platform APIs being demonstrated.
For example, `foo_basics` where `foo` corresponds to an IntelliJ Platform feature, framework, or component.
Some naming examples include `facet_basics` and `editor_basics`.
There is only one _basic_ sample per IntelliJ Platform API area.
For _advanced_ code samples, the name should reflect the complex functionality delivered by the plugin rather than the IntelliJ Platform APIs.
Advanced samples will be cross-referenced to the IntelliJ Platform APIs demonstrated in the sample.
Regardless of basic or advanced, an SDK plugin name is also known as the `Artifact ID` in the Gradle plugin wizard.
## Plugin Copyright Statements
Use the standard intellij-community copyright notice in all sample plugins authored by JetBrains:
```text
Copyright 2000-$today.year JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file."
```
The copyright statement must appear in every source file with the `$today.year` [Velocity](https://www.jetbrains.com/help/idea/copyright-profiles.html) template resolved.
## Plugin ID Conventions
The plugin ID (`<id>` in `plugin.xml`) always begins with `org.intellij.sdk`.
The plugin ID is known as the `Group ID` in the Gradle plugin wizard.
For _basic_ code samples, it is not necessary to include "basic" in the plugin ID.
A plugin like `facet_basics` has the ID `org.intellij.sdk.facet`.
## Plugin Package Names
Packages in plugins should begin with the plugin ID.
If there is only one package in a plugin, then the package name is the same as the plugin ID.
## Plugin Directory Structure
SDK sample code should have a standard directory footprint.
Standardized structure not only makes the samples easier to navigate and understand, but it builds on the default Gradle plugin project structure.
The following is the directory structure for a `basic_foo` plugin.
```text
code_samples/
basic_foo/
gradle/
src/
main/
java/
icons/
BasicFooIcons.java
resources/
icons/
sdk.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/
resources/
build.gradle
gradlew
gradle.bat
settings.gradle
```
## build.gradle Conventions
New SDK code samples should be developed [using Gradle](/tutorials/build_system.md).
As of this writing, the use of Gradle in SDK code samples still relies heavily on the `plugin.xml` for specifying the plugin configuration.
At a later, second phase, the SDK code samples will transition to rely more on the Gradle configuration.
The default contents of a `build.gradle` file are produced by the [Gradle project wizard](/tutorials/build_system/prerequisites.md#create-a-plugin-project-from-scratch).
A consistent structure for an SDK code sample's `build.gradle` file is important for clarity and is based on the default produced by the project wizard.
Comments in SDK code sample `build.gradle` files should only draw attention to the parts of the Gradle configuration that are unique for a plugin.
For SDK code samples a few alterations are needed to the default build.gradle file produced by the plugin wizard:
* Add the following statements 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:
```groovy
// Force javadoc rebuild before jar is built
jar.dependsOn javadoc
```
## 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.
Comment profusely about unique elements and configurations, and comment sparingly for the rest.
The sequence of elements in an SDK code sample `plugin.xml` file is:
* `<id>` Use the fully qualified [Plugin ID](#plugin-id-conventions).
* `<name>` The name value does not have to match the [Plugin Name](#naming-conventions-for-sdk-plugins).
It might reflect the functionality of the plugin.
The name must start with "SDK:".
* `<version>` The code sample's version in MAJOR.MINOR.FIX format.
* MAJOR corresponds to a significant upgrade in functionality.
* MINOR corresponds to minor refactoring and small improvements in functionality.
* 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.
* `until-build` attribute to an empty string `""`.
SDK code samples are reviewed with every major release to ensure compatibility with the latest IntelliJ Platform.
* `<description>` is a succinct explanation of what is being demonstrated and how a user would access the functionality.
* `<change-notes>` is an ordered list by version numbers with a brief description of changes for each version.
* `<vendor>` Set the value to `IntelliJ Platform SDK`.
Set the attributes:
* `email` omit this attribute.
* `url` to the JetBrains plugin repository `"https://plugins.jetbrains.com"`
* The remainder of the [plugin configuration elements](/basics/plugin_structure/plugin_configuration_file.md) should only appear if they are needed by a specific plugin.
## Testing
IntelliJ Platform SDK code samples should be built and tested against the `since-build` version.
Code samples should build cleanly, with no warnings or errors, and new code samples should pass all default IntelliJ IDEA code inspections.
Testers should complete the following checklist.
Here the term "IDE" means the IntelliJ Platform-based IDE in which the plugin is designed to run:
* The plugin should load in the IDE.
* The correct information about the plugin should display in the **Preferences \| Plugins** panel.
* If applicable, the plugin UI such as tool windows, menu additions, etc. should display correctly.
* The functionality of the plugin should be tested with a sample file.
* If applicable, the plugin should pass unit tests.

268
intro/sdk_style.md Normal file
View File

@ -0,0 +1,268 @@
---
title: Style Guide for SDK Documents
---
This document describes the writing style used in authoring open source IntelliJ Platform SDK documentation.
Before you begin, please read this page thoroughly as well as the [Code of Conduct](/CODE_OF_CONDUCT.md) and [License](https://github.com/JetBrains/intellij-sdk-docs/blob/master/LICENSE.txt) documents.
For information about contributing to the IntelliJ Platform itself, please visit [Contributing to the IntelliJ Platform](/basics/platform_contributions.md).
First and foremost, we should keep in mind our audience and their objectives:
_Someone reading technical content is usually looking to answer a specific question.
That question might be broad or narrowly-focused, but either way, our goal is to provide answers without distraction._
The style of the _Intellij Platform SDK_ documentation is captured by using a markup language named [_Markdown_](https://github.github.com/gfm/).
The following sections describe the SDK documentation style in terms of the Markdown formats:
* [Documentation Markup Style](#documentation-markup-style)
* [Page Format](#page-format)
* [Redirects](#redirects)
* [Table of Contents for a Page](#table-of-contents-for-a-page)
* [Text Format Conventions](#text-format-conventions)
* [Liquid tags and filters](#liquid-tags-and-filters)
* [Syntax highlighting](#syntax-highlighting)
* [Tables](#tables)
* [Links](#links)
* [Callouts](#notes-and-callouts)
* [Images](#images)
* [_SUMMARY.md Site Table of Contents](#summary-site-table-of-contents)
* [Repository Submodules](#repository-submodules)
## Documentation Markup Style
By default, when building the site, all files are copied to the destination `_site` folder.
Some files are excluded in the `_config.yml` and `sdkdocs-template/jekyll/_config-defaults.yml` files.
The documentation files themselves are [Markdown](https://github.github.com/gfm/) files (`*.md`) that get automatically converted to HTML when the site is built.
### Page Format
Only Markdown files beginning with a [YAML](https://yaml.org) header are converted to HTML.
If the Markdown file doesn't contain a header, it won't be converted.
In other words, to convert a `.md` file to HTML, it should look like this:
```yaml
---
---
Lorem ipsum...
```
The two lines at the top of the file are the markers of the YAML _front matter_.
Fields can be added in between these markers, and are used when generating the HTML.
Typically, this header is empty, although it is required by Jekyll (if omitted, the file isn't converted).
The YAML header can contain data that is used when generating the site.
For example, the page title can be specified as a simple piece of Markdown - `# Title`, or it can be specified in the YAML, and the page template displays it appropriately:
```yaml
---
title: The Title Of The Page
---
Lorem ipsum...
```
The YAML header can also include [redirect](#redirects) information.
Line spacing around headings in Markdown files generally doesn't affect the HTML conversion, but it does make MD pages more readable for authors:
* No space between a heading and the first content below it.
* One space before a heading if it is the same level or a sub-heading of the previous section.
* Two spaces before a heading that is higher-level than the heading of the previous section.
### Redirects
The documentation site is set up to include the [jekyll-redirect-from](https://github.com/jekyll/jekyll-redirect-from) plugin, which will generate "dummy" pages that automatically redirect to a given page.
For example, to specify that the `index.html` page be generated to redirect to `README.md`, the `README.md` file should include the following in the YAML header:
```yaml
---
redirect_from:
- /index.html
---
Lorem ipsum...
```
The redirect will create an `index.html` file that will automatically redirect to the generated `README.html` file.
Redirects enable the site URL to automatically show the `README.html` file - `http://localhost:4001/foo-test/` will try to load `index.html`, which will automatically redirect to `README.html`.
It is also useful to redirect when renaming or moving files.
Multiple redirects can be added to the YAML header.
### Table of Contents for a Page
The site is configured to use the [Kramdown Markdown converter](http://kramdown.gettalong.org), which adds some extra features over traditional Markdown.
For example, "attribute lists" that can apply attributes to the generated elements.
One useful attribute is `{:toc}`, which can be applied to a list item, which will get replaced with a list of links to header items.
E.g. the following list item will be replaced by links to all of the header items in the page:
```md
* Dummy list item
{:toc}
```
Further Kramdown features are described on the [converter page](https://kramdown.gettalong.org/converter/html.html), and attribute lists are described on the [syntax page](http://kramdown.gettalong.org/syntax.html).
Note that source code formatting is configured to use [GitHub Flavoured Mardown](https://help.github.com/articles/github-flavored-markdown/) and "code fences", see below.
### Liquid tags and filters
Jekyll uses the [Liquid](https://shopify.github.io/liquid/) templating language to process files.
This process means standard Liquid tags and filters are available.
There should be little need to use them, however, as the Markdown format is already quite rich.
See the [Jekyll site](http://jekyllrb.com/docs/templates/) for more details.
### Text Format Conventions
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 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`.
* [Links](#links) have a particular format depending on the type of link.
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_.
### 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:
```
// Source code goes here...
```
Syntax highlighting can be applied by specifying the language after the first set of ticks:
```csharp
// Some C# code
```
```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.
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
The site is also configured to highlight a range of files in the source code, by specifying `{start-end}` which is the start and end line of the highlighting:
```java{2-3}
// Not highlighted
// Highlighted
// Highlighted
// Not highlighted
```
-->
### Tables
The Kramdown parser also supports tables.
The syntax is to use the pipe (`|`) and minus symbols:
```md
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Blah | Blah | Blah |
```
### Links
Links are handled as normal Markdown links and can be anchored to external sites, pages within the sites, or headings in the sites.
When a Markdown header is converted to an HTML header, it is assigned an ID so that it can be linked.
For example, `## Introduction` will get the ID of `introduction`, and can be linked either in the same page or cross-page as described below.
Links to files in the IntelliJ Platform (`intellij-community`) repository use `upsource:///` instead of the full URL to the repository.
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.
General links have one of the following formats:
* `[External site](http://example.org)` links to an external site.
* Linking to pages in the SDK documentation:
* `[SDK doc page in current directory](Page2.md)` links to an SDK doc page in the same directory as the current page.
Note that the extension is `.md`, _NOT_ `.html`.
* `[SDK page in another folder](/Folder2/Page2.md)` links to a page in another folder.
Note that the URL is navigating from the project root - this works even if the site is hosted in a sub-folder (e.g. this link will work for `http://localhost:4000/devguide/Folder2/Page2.html`).
Relative links also work (`../Folder2/Page2.md`).
* Linking to specific _sections_ on pages in the SDK documentation.
The anchor name will be all lower case, and spaces are replaced with `-`, e.g. `## Page setup` becomes `#page-setup`.
* `[Link to a section on the current page](#another-section)` links to a heading on the current page.
* `[Link to the section on another page](Page2.md#another-section)` links to a heading on another page.
### Notes and callouts
Notes and callouts can be specified using the blockquote syntax.
The converter looks at the first following word to see if it is bold.
If so, it applies a callout style.
The example below will be displayed as a callout, styled as a "note":
> **NOTE** This is a note
> **NOTE** This is a note
The styles available for callouts are:
* TODO - Generally not used in SDK documentation.
Embed `<--! //TODO: explanation... -->` instead, which is not visible in published documentation.
* TIP - Information that makes the reader more productive.
* NOTE - Information that is important for the reader to understand.
This callout is reserved for key points and concepts.
* WARNING - Information critical to the user.
Use this callout for information that prevents failures or errors.
### Images
Images can be included by adding the file directly to the `intellij-sdk-docs` repository.
Each subject directory typically has an `img` subdirectory.
Keep images close to the corresponding documentation file in the repository directory structure.
Images in this documentation are generally screenshots.
The preferred image format is PNG at 144 DPI resolution.
A resolution of 72 DPI is acceptable but may look blurry on high-resolution monitors.
It is important to reduce the size of image files to prevent bloating the repository and impacting the performance of the documentation site.
Resize an image to be nearly the desired width on a documentation page.
Reducing an image's dimensions is the most effective way to reduce image file size.
Also optimize the image files using a tool such as the [PNG optimizer](https://plugins.jetbrains.com/plugin/7942-png-optimizer).
Images are embedded in a document by adding a Markdown link to the image like so:
![Alt text](path-to-img.png)
If the width of an image needs to be adjusted, use Kramdown markup:
![Alt text](path-to-img.png){:width="42px"}
## _SUMMARY Site Table of Contents
The table of contents for the site is displayed in the tree view on the left-hand side of the site, and it is generated from the `_SUMMARY.md` file.
It is a simple Markdown list, with each item in the list being a link to another Markdown page, either in the root folder, or sub-folders.
The list can have nested items, which are displayed as child items in the table of contents.
> ***WARNING*** Every Markdown (`*.md`) document within the SDK repository (`intellij-sdk-docs`) must have an entry in `_SUMMARY.md`.
```md
# Summary
* [Introduction](README.md)
* [About This Guide](Intro/About.md)
* [Key Topics](Intro/KeyTopics.md)
```
The contents can be split into "parts" by separating the list into several lists, each new list starting with a level 2 heading (`##`).
```md
# Summary
* [Introduction](README.md)
* [About This Guide](Intro/About.md)
* [Key Topics](Intro/KeyTopics.md)
## Part I - Extending the Platform
* [Getting Started](Docs/GettingStarted.md)
* ...
```
If a node doesn't have a link but is just plain text, it will still appear in the table of contents but will be greyed out and not clickable.
It acts as a placeholder for a documentation item.
A placeholder is useful to keep track of what should be documented, but hasn't yet, and can be useful to show readers that the topic exists, but isn't yet documented (Pull Requests always welcome!).