IntelliJ プラットフォーム SDK プラグイン開発ガイド

主なトピック行動規範
ページの編集 (英語)

貢献する

貢献してくれてありがとう! プルリクエストを送信する前に知っておくと便利なことがいくつかあります。

IntelliJプラットフォームへの貢献

このドキュメントでは、IntelliJ SDKドキュメントの貢献ガイドラインについて説明します。IntelliJプラットフォームへの貢献については、IntelliJプラットフォームへの貢献を参照してください。

環境のセットアップ

このサイトは、Rubyで書かれた一般的な静的サイト生成プログラムであるJekyll(英語)を介して実行されます。変更が正しいことを確認するために、ローカルにホストすることができます。セットアップが完了したら、rake previewを呼び出すのと同じくらい簡単にサイトを実行できます。

Alternatively, the site can also be hosted in a Dockerコンテナー(英語) . 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 . 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, so it is a known working environment.

Dockerによる開発

Dockerを使用するには、以下の手順に従ってください。

  • まず、Docker Toolbox(英語)を使用してDockerをインストールします。
  • WindowsとMacでは、Dockerホスト仮想マシンを起動します（「Docker Quickstartターミナル」を起動するか、「Kitematic」を実行してください）。詳細については、docker.com(英語)のスタートガイドを参照してください。
  • intellij-sdk-docs (英語)リポジトリをローカルマシンに複製し、 sdkdocs-template サブモジュールを初期化するを複製します。
  • 現在のディレクトリーをgit repoの親ディレクトリーに変更します。
  • docker build -t intellij-sdk-docs .を実行します。これにより、現在のフォルダーからdockerイメージが構築され、intellij-sdk-docsというタグが付けられます。
    • これは、Dockerクイックスタートターミナルなど、さまざまな DOCKER_* 環境変数が設定されたコマンドプロンプトから実行する必要があります。
  • docker run -p 4000:4000 -v $PWD:/usr/src/app intellij-sdk-docsを実行します。このコマンドは次のようになります。
    • intellij-sdk-docsというdockerコンテナーを起動します。
    • dockerコンテナーのポート4000をdockerクライアントのポート4000に転送します。
    • 現在のディレクトリーをマウントする（$PWD はUnixスタイルの環境変数で、Windowsでは %CD% を使用するか、フルパスを指定することができます）、dockerコンテナー内の /usr/src/app としてマウントします。つまり、dockerイメージに intellij-sdk-docs レポが /usr/src/appというフォルダーとして表示されます。
    • Dockerfileの CMD 命令で特定のコマンドを実行します。rake bootstrapはすべての前提条件が確実に実行され、rake previewはサイトを構築してホストを開始します。
  • 最後に、http://localhost:4000/intellij/sdk/docs/(英語)にアクセスするか、またはdockerクライアント仮想マシンのIPアドレスを使用して、新しく作成したサイトにアクセスできます（上記の注を参照）。

ローカルに開発する

ドキュメントサイトを構築するために、必要となるでしょう：

  • Ruby 2 - JekyllはRubyアプリケーションです。
  • Ruby 2 DevKit（Windows用） - Jekyllの依存関係の一部をコンパイルする必要があり、DevKitをインストールする必要があります。
  • gem install bundler - the site uses Bundler(英語) 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

OS XにはRubyがすでにインストールされています。必要な手順は次のとおりです。

  • gem install bundler

Windows

  • Ruby 2(英語)とRuby 2 DevKit(英語)をインストールする (gemsの1つはネイティブコンポーネントを構築する必要があります)
    • DevKitをインストールした後、config.yml ファイルを編集して、Rubyインストールを指すようにしてください

Windowsのパッケージマネージャーチョコレート(英語)を使用すると、これは簡単になります。

  • choco install ruby
  • choco install ruby2.devkit
    • DevKitをインストールした後、config.yml ファイルを編集して、Rubyインストールを指すようにしてください。
    • デフォルトでは、これは C:\tools\DevKit\config.ymlです
    • - C:\tools\ruby21 行を追加します (先行するマイナス記号を含む)

環境のブートストラップ

  1. Bundlerがインストールされていることを確認する - gem install bundler
  2. Windowsでは、devkitvars.bat ファイルが現在のコマンドプロンプト（ c:\tools\DevKit\devkitvars.batなど）で実行されていることを確認してください。
  3. ドキュメントサイトをクローンします。
  4. sdkdocs-template サブモジュール（ git submodule init および git submodule update）の初期化と更新
  5. rake bootstrap - this uses Bundler to download all required gems.
  6. rake preview - これによりサイトが構築され、ローカルWebサーバーでホストされます。

サイトの構築とプレビュー

サイトを構築してテストするには、rake previewを実行するだけです。これはサイトを構築し、提供された設定を使用してそれをホストします。ホステッドサイトのURLは画面に表示され、_config.ymlで定義された baseurl フィールドによって異なります。

マークアップ

デフォルトでは、サイトを構築するときに、すべてのファイルがコピー先の _site フォルダーにコピーされます。一部のファイルは、_config.yml および sdkdocs-template/jekyll/_config-defaults.yml ファイルで除外されます。ドキュメントファイル自体は、サイト構築時に自動的にHTMLに変換されるMarkdown(英語)ファイル（.md）です。

ただし、YAML(英語)ヘッダーで始まるマークダウンファイルのみが変換されます。マークダウンファイルにヘッダーが含まれていない場合は、変換されません。つまり、.md ファイルをHTMLに変換するには、次のようになります。

--- --- # Introduction Lorem ipsum...

ファイルの先頭にある2行は、YAMLの "front matter"のマーカーです。フィールドは、これらのマーカーの間に追加することができ、HTMLを生成するときに使用されます。通常、このヘッダーは空白になりますが、これはJekyllによって必要とされます（省略された場合、ファイルは変換されません）。

YAMLヘッダーには、サイトを生成する際に使用されるデータを含めることができます: 例：ページタイトルはマークダウンの単純な部分として指定することができます - # Title、またはYAMLで指定することができ、ページテンプレートはそれを適切に表示します：

--- title: The Title Of The Page --- Lorem ipsum...

YAMLヘッダはリダイレクト情報も含むことができます。

_SUMMARY.md

サイトの目次は、サイトの左側のツリービューに表示され、_SUMMARY.md ファイルから生成されます。これは単純なマークダウンリストです。リスト内の各項目は、ルートフォルダーまたはサブフォルダー内の別のマークダウンページへのリンクです。リストにはネストした項目を含めることができます。これは目次の子項目として表示されます。

# Summary * [Introduction](README.md) * [About This Guide](Intro/About.md) * [Key Topics](Intro/KeyTopics.md)

リストを複数のリストに分けることにより、コンテンツを「パーツ」に分割することができます。各リストはレベル2見出し（##）で始まります。

# 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) * ...

ノードにリンクがなく、単なるプレーンテキストである場合、それはまだ目次に表示されますが、グレー表示され、クリックできません。ドキュメントアイテムのプレースホルダとして機能します。これは文書化されるべきものを追跡できますが、まだそれはされていません、そしてトピックが存在するがまだ文書化されていないことを読者に示すのに役立ちます（プルリクエストはいつでも大歓迎です）。

リダイレクト

ドキュメントサイトはjekyll-redirect-from(英語)プラグインを含むように設定されており、自動的に指定ページにリダイレクトする「ダミー」ページを生成します。例： index.html ページを生成して README.mdにリダイレクトするように指定するには、README.md ファイルでYAMLヘッダーに次のものを含める必要があります。

--- redirect_from: - /index.html --- # Introduction Lorem ipsum...

これにより、生成された README.html ファイルに自動的にリダイレクトされる index.html ファイルが作成されます。これは、サイトのURLに README.html ファイルを自動的に表示させるのに非常に便利です。http://localhost:4001/foo-test/ は index.htmlをロードしようとします。index.htmlは自動的に README.htmlにリダイレクトします。

また、ファイル名の変更や移動時にリダイレクトすると便利です。複数のリダイレクトをYAMLヘッダーに追加できます。

目次

このサイトはKramdown Markdownコンバータ(英語)を使用するように構成されています。これは、生成された要素に属性を適用できる「属性リスト」など、従来のマークダウンに比べていくつかの追加機能を追加します。

有用な属性の1つは、{:toc}です。この {:toc}はリストアイテムに適用でき、ヘッダアイテムへのリンクのリストで置き換えられます。例: 次のリスト項目は、ページ内のすべてのヘッダー項目へのリンクに置き換えられます。

* Dummy list item {:toc}

その他のKramdown機能はコンバータページ(英語)に、属性リストは構文ページ(英語)に記載されています。ソースコードのフォーマットはGitHubフレーバードマロード(英語)と「コードフェンス」を使用するように設定されています。下記を参照してください。

Liquidタグとフィルタ

JekyllはLiquid(英語)テンプレート言語を使用してファイルを処理します。これは標準のLiquidタグとフィルタが利用可能であることを意味します。ただし、Markdown形式はすでに非常に豊富であるため、それらを使用する必要性はほとんどありません。詳しくはJekyllサイト(英語)を参照してください。

構文の強調表示

ソースコードはGitHub風味のMarkdown(英語)コードフェンスを使って表すことができます。

``` // Source code goes here... ```

構文強調表示は、最初のティックセット後に言語を指定することによって適用できます。

```csharp // Some C# code ``` ```java // Some Java code ```

これはサポートされている言語(英語)のリストです （そしてもちろんKotlin(英語)も）。

コードサンプルを簡潔にし、不要な「周囲の」コードやインポートステートメントを避けてください。

テーブル

Kramdownパーサーはテーブルもサポートしています。構文は、パイプ（|）とマイナス記号を使用することです。

```md | Column 1 | Column 2 | Column 3 | |----------|----------|----------| | Blah | Blah | Blah | ```

リンク

リンクは通常のマークダウンリンクとして処理され、外部サイト、サイト内のページ、またはサイト内の見出しにリンクすることができます。MarkdownヘッダーがHTMLヘッダーに変換されるとき、それはIDを割り当てられます、それでそれはリンクされることができます。例: ## Introduction は introductionのIDを取得し、同じページ [click here](#introduction) またはクロスページ [click here](page.html#introduction)のいずれかにリンクできます。アンカー名はすべて小文字になり、スペースは -に置き換えられます。 ## Page setup は #page-setupになります。

  • [External site](http://example.org) は外部サイトにリンクします
  • [Other page in current directory](Page2.md) は、現在のページと同じディレクトリーにあるページにリンクします。拡張子は .mdであり、.htmlではないことに注意してください。
  • [Page in another folder](/Folder2/Page2.md) は別のフォルダー内のページにリンクします。URLがルートからナビゲートしていることに注意してください。サイトがサブフォルダーにホストされていても機能します（たとえば、このリンクは http://localhost:4000/devguide/Folder2/Page2.htmlで動作します）。相対リンクも機能します（../Folder2/Page2.md）。
  • [Link to section on another page](Page2.md#another-section) は別のページの見出しにリンクします。見出しのIDは、テキストを小文字にしてスペースを -に置き換えることによって生成されます。
  • [Link to section on current page](#another-section) は、現在のページの見出しにリンクします。

ノートとコールアウト

ノーツとコールアウトは、ブロッククォート構文を使用して指定できます。コンバータは最初の次の単語を見て、それが太字であるかどうかを調べます。そうであれば、それは吹き出しスタイルとして適用されます。例えば：

> **NOTE** This is a note

吹き出しとして表示され、「メモ」と書式設定されます。コールアウトに使用できる他のスタイルは、「メモ」、「警告」、「ヒント」および「トゥード」です。

イメージ

リポジトリにファイルを直接追加し、イメージにリンクを追加することで、イメージを含めることができます：

![Alt text](path-to-img.png)

縮小サイズのスクリーンショットを高解像度で作成してください。

![Alt text](path-to-img.png){:width="42px"}

サブモジュールの単語

sdkdocs-template リポジトリはサブモジュールとして追加され、プライベート webhelp-template リポジトリのサブモジュールも含まれています。 sdkdocs-template リポジトリには、ビルドタイムスクリプトとコンパイルされたミニJSおよびCSSが含まれており、サイトを実行できます。プライベート webhelp-template リポジトリには、JSとCSSを構築するためのコードが含まれています。現在はクローズドソースですが、ある時点でオープンソースにする計画です。その場合、2つのreposがマージされる可能性があります。

クローン作成後、サブモジュールを初期化して更新する必要があります。

``` git submodule init git submodule update ```

これにより、.gitmodules ファイルが作成され、sdkdocs-template フォルダーにサブモジュールが登録され、ファイルがチェックアウトされます。（リポジトリをサブモジュールとして追加すると、.git フォルダーは取得されませんが、代わりに .git フォルダーの場所を指す .git ファイルが取得されます。

サブモジュールは、git pullなどの通常のgitコマンドを使用して更新できます。 git checkoutを使用して別のブランチに切り替えることができます。また、現在チェックアウトされているリビジョンの変更は、通常のgitコマンドと同じようにメインのrepoにコミットする必要があります。最初は特定のリビジョンで複製され、ブランチ.updateの一部としては複製されません

サブモジュールに変更が加えられた場合は、ブランチ上でクローンに変更し、プルリクエストを送信する必要があります。変更を行いコミットすることができ、ホスティングレポはサブモジュールの現在のバージョンへのポインタをコミットする必要があります。

sdkdocs-templateに問題がある場合は、してください問題を提起(英語)。

主なトピック行動規範
最終更新日: