Provide detailed documentation for using IntelliJ

Change-Id: I4a37a270d9a10694daad6a26756dd0e81d591c54

Documentation/dev-bazel.txt

@@ -12,6 +12,7 @@ Nice to have:
 * local.properties proxy config.
 * coverage
 
+[[installation]]
 == Installation
 
 You need to use Java 8 and Node.js for building gerrit.
@@ -137,20 +138,8 @@ is not regenerated.
 
 === IntelliJ
 
-The Gerrit build works with Bazel's [IntelliJ
-plugin](https://ij.bazel.io). Do the following:
-
-  * Install the plugin (requires IJ 2016.2 or newer)
-  * Restart IntelliJ
-  * Select "Import Bazel Project" from the homescreen
-  * Select "Workspace": (directory holding gerrit source)
-  * Select "Import from workspace > Project view" : `.bazelproject`
-  * Once the project was created, copy `tools/intellij/gerrit_daemon.xml` to
-    `.idea/runConfigurations/gerrit_daemon.xml` in your IntelliJ output
-  * In Settings > Appearance & Behavior > Path Variables create a new path
-    variable called `TESTSITE_PATH` and provide the path to your local testsite
-    as value
-
+The Gerrit build works with Bazel's link:https://ij.bazel.io[IntelliJ plugin].
+Please follow the instructions on <<dev-intellij#,IntelliJ Setup>>.
 
 === Eclipse
 

Documentation/dev-intellij.txt

@@ -0,0 +1,73 @@
+= IntelliJ Setup
+
+== Prerequisites
+You need an installation of IntelliJ of version 2016.2 or newer.
+
+In addition, Java 8 must be specified on your path or via `JAVA_HOME` so that
+building with Bazel via the Bazel plugin is possible.
+
+TIP: If the synchronization of the project with the BUILD files using the Bazel
+plugin fails and IntelliJ reports the error **Could not get Bazel roots**, this
+indicates that the Bazel plugin couldn't find Java 8.
+
+Bazel must be installed as described by
+<<dev-bazel#installation,Building with Bazel - Installation>>.
+
+== Installation of the Bazel plugin
+
+. Go to *File -> Settings -> Plugins*.
+. Click on *Browse Repositories*.
+. Search for the plugin `IntelliJ with Bazel`.
+. Install it.
+. Restart IntelliJ.
+
+== Creation of IntelliJ project
+
+. Go to *File -> Import Bazel Project*.
+. For *Use existing bazel workspace -> Workspace*, select the directory
+containing the Gerrit source code.
+. Choose *Import from workspace* and select the `.bazelproject` file which is
+located in the top directory of the Gerrit source code.
+. Adjust the path of the project data directory and the name of the project if
+desired.
+
+TIP: The project data directory can be separate from the source code. One
+advantage of this is that project files don't need to be excluded from version
+control.
+
+Unfortunately, the created project seems to have a broken output path. To fix
+it, please complete the following steps:
+
+. Go to *File -> Project Structure -> Project Settings -> Modules*.
+. Switch to the tab *Paths*.
+. Click on *Inherit project compile output path*.
+. Click on *Use module compile output path*.
+
+== Run configurations
+
+=== Pre-configured run configurations
+
+In order to be able to use the pre-configured run configurations, the following
+steps are necessary:
+
+. Make sure that the folder `runConfigurations` exists within
+`$(project_data_directory)/.idea`. If it doesn't exist, create it.
+. Specify the IntelliJ path variable `GERRIT_TESTSITE`. (This configuration is
+shared among all IntelliJ projects.)
+.. Go to *Settings -> Appearance & Behavior -> Path Variables*.
+.. Click on the *+* to add a new path variable.
+.. Specify `GERRIT_TESTSITE` as name and the path to your local test site as
+value.
+
+The copied run configurations will be added automatically to the available run
+configurations of the IntelliJ project.
+
+==== Gerrit Daemon
+Copy `$(gerrit_source_code)/tools/intellij/gerrit_daemon.xml` to
+`$(project_data_directory)/.idea/runConfigurations/`.
+
+This run configuration starts the Gerrit daemon similarly as
+<<dev-readme#run_daemon,Running the Daemon>>.
+
+NOTE: The <<dev-readme#init,Site Initialization>> has to be completed
+before this run configuration works properly.

Documentation/dev-readme.txt

@@ -76,7 +76,7 @@ them as "Generated Sources Root":
 
 === Build based on Bazel
 
-Please refer to <<dev-bazel#_intellij,IntelliJ Setup>> for detailed
+Please refer to <<dev-intellij#,IntelliJ Setup>> for detailed
 instructions.
 
 == Mac OS X
@@ -174,7 +174,7 @@ please refer to:
 link:dev-buck.html#tests[Running integration tests with Buck].
 For Bazel, please refer to <<dev-bazel#tests,Running Unit Tests with Bazel>>.
 
-
+[[run_daemon]]
 === Running the Daemon
 
 The daemon can be directly launched from the build area, without

Documentation/index.txt

@@ -64,6 +64,7 @@
 .. link:dev-buck.html[Building with Buck]
 .. link:dev-bazel.html[Building with Bazel]
 .. link:dev-eclipse.html[Eclipse Setup]
+.. link:dev-intellij.html[IntelliJ Setup]
 .. link:dev-contributing.html[Contributing to Gerrit]
 . Plugin Development
 .. link:dev-plugins.html[Developing Plugins]

tools/intellij/gerrit_daemon.xml

@@ -2,7 +2,7 @@
   <configuration default="false" name="gerrit_daemon" type="Application" factoryName="Application" singleton="true">
     <extension name="coverage" enabled="false" merge="false" sample_coverage="true" runner="idea" />
     <option name="MAIN_CLASS_NAME" value="Main" />
-    <option name="PROGRAM_PARAMETERS" value="daemon --console-log --show-stack-trace -d ${TESTSITE_PATH}" />
+    <option name="PROGRAM_PARAMETERS" value="daemon --console-log --show-stack-trace -d ${GERRIT_TESTSITE}" />
     <option name="WORKING_DIRECTORY" value="file://$MODULE_DIR$" />
     <option name="ALTERNATIVE_JRE_PATH_ENABLED" value="false" />
     <option name="ALTERNATIVE_JRE_PATH" />