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

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

貢献する

寄付いただきありがとうございます! プルリクエストを送信する前に知っておくべき有用な情報はほとんどありません。

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

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

環境のセットアップ

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

あるいは、サイトをDocker コンテナ(英語)でホストすることもできます。MacとWindowsでは、これはサイトが仮想マシンでホストされていることを意味します。Dockerはこのコンテナーを保守し、 Dockerfile の指示に基づいてそれを構築します。イメージの構築時にすべての依存関係（Rubyなど）が自動的にインストールされるため、手動の構成手順が削減されます。Dockerイメージは公開サイトの構築にも使用されるため、既知の作業環境です。

Dockerによる開発

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

  • まず、Dockerツールボックス(英語)を使用して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 - このサイトでは、グローバルにローカルオペレーティングシステムにインストールするのではなく、Bundler(英語)を使用してリポジトリ内のgem依存関係を管理しています。このコマンドを実行してBundlerツールセットをグローバルにインストールします。

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 - これはBundlerを使用して必要な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サイト(英語)を参照してください。

構文の強調表示

ソースコードは、3つのバックティックである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)

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

サブモジュールの単語

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に問題がある場合は、してください問題を提起(英語)。

主なトピック
最終更新日: