IntelliJプラットフォームSDKへの貢献
このドキュメントでは、オープンソースのIntelliJ プラットフォーム SDKドキュメントとサンプルコードに対する貢献ガイドラインを説明します。SDKへのコンテンツの提供を始める前に、このページと行動規範およびライセンス(英語)のドキュメントをよく参照してください。IntelliJプラットフォーム自体への貢献については、IntelliJプラットフォームへの貢献を参照してください。
SDKコンテンツを作成してプルリクエストを送信する前に知っておくと便利なことがいくつかあります。
ドキュメントビルド環境の設定
このサイトは、Rubyで書かれた一般的な静的サイト生成プログラムであるJekyll(英語)を介して実行されます。変更が正しいことを確認するために、ローカルにホストすることができます。セットアップが完了したら、rake preview
を呼び出すのと同じくらい簡単にサイトを実行できます。
あるいは、このサイトはDockerコンテナー(英語)でホストすることもできます。MacとWindowsでは、これはサイトが仮想マシンでホストされていることを意味します。Dockerはこのコンテナーを保守し、 Dockerfile
の指示に基づいてそれを構築します。イメージの構築時にすべての依存関係(Rubyなど)が自動的にインストールされるため、手動の構成手順が削減されます。Dockerイメージは公開サイトの構築にも使用されるため、既知の作業環境です。
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クイックスタートターミナルなど、さまざまな
-
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ツールセットをグローバルにインストールするには、このコマンドを実行します。
macOS
macOSにはRubyが既にインストールされています。必要な手順は次のとおりです。
gem install bundler
Windows
- Ruby 2(英語)とRuby 2 DevKit(英語)をインストールする (gemsの1つはネイティブコンポーネントを構築する必要があります)
- DevKitをインストールした後、
config.yml
ファイルを編集して、Rubyインストールを指すようにしてください
- DevKitをインストールした後、
Windows用のパッケージマネージャーであるChocolatey(英語)を使用すれば、このインストールはより簡単になります。
choco install ruby
choco install ruby2.devkit
- DevKitをインストールした後、
config.yml
ファイルを編集して、Rubyインストールを指すようにしてください。 - デフォルトでは、これは
C:\tools\DevKit\config.yml
です -
- C:\tools\ruby21
行を追加する (先行するマイナス記号を含む)
- DevKitをインストールした後、
ドキュメント構築環境のブートストラップ
- Bundlerがインストールされていることを確認してください -
gem install bundler
。 - Windowsでは、
devkitvars.bat
ファイルが現在のコマンドプロンプト(c:\tools\DevKit\devkitvars.bat
など)で実行されていることを確認してください。 - ドキュメントサイトをクローンします。
-
sdkdocs-template
サブモジュールの初期化と更新 -git submodule init
およびgit submodule update
rake bootstrap
- これはBundlerを使用して必要なすべてのgemsをダウンロードします。rake preview
- これによりサイトが構築され、ローカルWebサーバーでホストされます。
サイトの構築とプレビュー
サイトを構築してテストするには、rake preview
を実行します。これはサイトを構築し、提供された設定を使用してそれをホストします。ホスティングサイトのURLは画面に表示され、_config.yml
で定義された baseurl
フィールドに依存します。
ドキュメントリポジトリサブモジュール
sdkdocs-template
ディレクトリーは実際にはGitサブモジュールであり、プライベート webhelp-template
リポジトリへのサブモジュールが含まれています。 sdkdocs-template
リポジトリには、サイトの実行を可能にするビルドスクリプトと、コンパイルおよび縮小されたJSおよびCSSが含まれています。プライベート webhelp-template
リポジトリには、JSとCSSを構築するためのコードが含まれています。現在はクローズドソースですが、ある時点でオープンソースにすることを計画しています。その場合は、2つのリポジトリがマージされる可能性があります。
クローン作成後、サブモジュールを初期化して更新する必要があります。
git submodule init
git submodule update
初期化すると .gitmodules
ファイルが作成され、sdkdocs-template
フォルダーにサブモジュールを登録してファイルをチェックアウトします。リポジトリをサブモジュールとして追加しても、.git
フォルダーは取得されず、代わりに .git
フォルダーの実際の場所を指す .git
ファイルが取得されます。
サブモジュールは、git pull
などの通常のgitコマンドを使用して更新できます。 git checkout
を使用して別のブランチに切り替えることができます。現在チェックアウトされているリビジョンに対する変更は、gitコマンドを使用してメインリポジトリにコミットする必要があります。サブモジュールは、ブランチ.updateの一部としてではなく、特定のリビジョンで最初に複製されます。
サブモジュールに変更を加えた場合は、ブランチからクローンに変更を加えてプルリクエストを送信する必要があります。変更を加えてコミットすることができ、ホスティングリポジトリは現在のバージョンのサブモジュールへのポインタをコミットする必要があります。
sdkdocs-template
に課題がある場合は、してください課題を提起(英語)。
IntelliJプラットフォームSDKコンテンツの作成
IntelliJプラットフォームSDKへのコンテンツの貢献は大歓迎です。GitHub(英語)からオープンソースSDKプロジェクトをダウンロードまたは複製し、追加または変更を加えて、プルリクエストを送信してください。コンテンツを作成または変更する前に、次のガイドを参照してください。
- SDKドキュメントスタイルガイド。このガイドでは、Markdownの構文に関するドキュメントの規則について説明します。常にサイトのプレビューを使用してドキュメントの変更をテストしてください。
- SDKコードサンプルガイドライン。このドキュメントでは、コードサンプルの編成、プロジェクト設定、および命名規則について説明します。SDKコードサンプルをビルドしてテストすることで、コードの変更を常にテストしてください。