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

CONTRIBUTING.md with instructions for building

Browse Source
This commit is contained in:
Matt Ellis 2015-07-10 16:25:26 +01:00
parent 3f00823347
commit b63368b939
2 changed files with 210 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

280
CONTRIBUTING.md
View File

@ -1,109 +1,247 @@
# Contributing
Thanks for contributing! Here are few useful things to know before submitting your Pull Request.
* Licensing - see [LICENSE.txt](LICENSE.txt)
* [Setting up your environment](#setting-up-your-environment)
* [Markup](#markup)
* _SUMMARY.md
* [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)
## Setting up your environment
This site is a [Jekyll](http://jekyllrb.com) site, 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`.
### Prerequisites
In order to build the documentation site, you will need:
* Ruby 2 - Jekyll is a Ruby application
* Ruby 2 DevKit (for Windows)
* Python 2 - the [Pygments](https://github.com/tmm1/pygments.rb) gem uses Python for syntax highlighting.
* `gem install bundler` - the site uses [Bundler](http://bundler.io) to manage gem dependencies within the repo, rather than globally installing to the local operating system.
**OS X**
OS X comes with Ruby and Python already installed. The only steps required are:
* `gem install bundler`
**Windows**
* Install [Ruby 2](http://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
* Install [Python 2](https://www.python.org/downloads/windows/) (2.7 is recommended)
This is made easier if you use [Chocolatey](https://chocolatey.org), a package manager for Windows:
* `choco install ruby`
* `choco install ruby2.devkit`
* After installing the DevKit, make sure to edit the `config.yml` file to point to the Ruby installation.
* By default, this is `C:\tools\DevKit\config.yml`
* Add the line `- C:\tools\ruby21` (including the leading minus sign)
* `choco install python2`
**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
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`
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.
### 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`.
## Markup
By default, when building the site, all files are copied across. Some are excluded in the `_config.yml` and `sdkdocs-template/jekyll/_config-defaults.yml` files. The documentation files themselves are [Markdown](http://daringfireball.net/projects/markdown/) files (`.md`) that get automatically converted to HTML when the site is built.
However, only markdown files beginning with a [YAML](http://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
---
title: Contribution Guidelines
---
This document explains how to contribute changes to the *IntelliJ Platform SDK Documentation* project.
# Introduction
## Licensing
Project source code terms of use, reproduction, and redistribution is defined by
[Apache 2.0 license](http://www.apache.org/licenses/LICENSE-2.0.html)
Lorem ipsum...
```
## Contributing Changes
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).
### Users with Write Access
To contribute your changes
[clone the project](https://help.github.com/articles/fetching-a-remote/),
implement your changes, and
[push](https://help.github.com/articles/pushing-to-a-remote/) them to the repository.
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:
```md
---
title: The Title Of The Page
---
### Users with Read-Only Access
Lorem ipsum...
```
To contribute you changes use a
[pull request](https://help.github.com/articles/using-pull-requests/).
[Creating a pull request](https://help.github.com/articles/creating-a-pull-request/)
article on GitHub explains how to do it.
The YAML header can also include [redirect](#redirects) information.
## Setting Up Environment
To build and run the project locally you need to set up its development environment,
Refer to the
[README](https://github.com/JetBrains/intellij-sdk-docs/blob/master/README.md)
section of this project.
### _SUMMARY.md
## Project Structure
The project contain the following major types of content:
1. Articles
An article describes some part of the API and general rule of using it in a free form.
2. Step-by-step tutorials
3. Code samples
The table of contents 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
### Markup
* [Introduction](README.md)
* [About This Guide](Intro/About.md)
* [Key Topics](Intro/KeyTopics.md)
```
Documents are written in
[Markdown](https://en.wikipedia.org/wiki/Markdown)
markup template language.
Processing of Markdown source code and conversion into HTML is made by
[Kramdown](http://kramdown.gettalong.org/syntax.html) library.
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
### Creating an Article
* [Introduction](README.md)
* [About This Guide](Intro/About.md)
* [Key Topics](Intro/KeyTopics.md)
To post an article, create a Markdown document inside of the project directory structure.
Jekyll engine will process all the Markdown files inside the project and create corresponding static HTML pages with same relative paths for them.
To process a Markdown file you need to refer to it's HTML counterpart in *\_SUMMARY.md*
### Table of Contents and \_SUMMARY.md
## Part I - Extending the Platform
* [Getting Started](Docs/GettingStarted.md)
* ...
```
File
[\_SUMMARY.md](https://github.com/JetBrains/intellij-sdk-docs/blob/master/_SUMMARY.md)
located in the root directory defines project's hierarchical structure displayed on the left side of the page in a tree form.
Place the name of an article and a link relatively to the site root to the corresponding HTML document to *\_SUMMARY.md* to list the article in TOC.
Headers without links to corresponding files won't be visible. Files not included in the listing wont be processed.
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 like 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!).
### Formatting Rules
### Redirects
### Text
To make the source code easy to read, start every new sentence from a new line.
Avoid semicolons, long sentences, and complicated formulations.
The documentation site is set up to include the `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](http://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](http://liquidmarkup.org) 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 back ticks:
```
// 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/github/linguist/blob/master/lib/linguist/languages.yml).
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
Place every link separately on a new line
```
Please refer to the
[following article](http://link.address)
to get more information
```
Links are handled as normal markdown links, and can be links 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.
## Project Structure
### Notes and callouts
All the documentation is logically divided into three major parts:
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:
* **Basics**
Contains information required to get familiar with the plugin development environment and the API
* **Architecture Reference Guide**
More in-depth API description
* **Tutorials**
Series of steps and code samples that show how parts of the API can be use in practice
Your article should be placed in one of these three categories dependently on the type of the content.
### Child Documents
To place child documents, create a subdirectory named like a parent article and place all the child documents in it.
> **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
To place images for an article, in the article's directory root create a subfolder named \<article_name\>/img.
Images can be included by adding the file directly to the repository and adding a link to the image like so:
```md
![Alt text](path-to-img.png)
```
Please downscale screenshots made at high resolution.
## 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 there are any problems with the `sdkdocs-template`, please [raise an issue](https://github.com/JetBrains/sdkdocs-template/issues).

2
sdkdocs-template

@ -1 +1 @@
Subproject commit 7cd87d50a6a44b90e33c48f6c3d018343663e58e
Subproject commit 22db05abdf7b6cddcf37799add1655a60090485c