Document a more modern way of using IntelliJ with our Bazel project. (#6328)

* Document a more modern way of using IntelliJ with our Bazel project.

Specifically, avoid `bazel-project-view` in favor of excluding a few
slow/unnecessary directories.

CHANGELOG_BEGIN
CHANGELOG_END

* Add .bazel-cache to .bazelignore instead of .bazelproject.

* Bazel: Don't mention a particular version of IntelliJ; just link.

Trust the canonical source.

.bazelignore

@@ -1,3 +1,4 @@
+.bazel-cache
 dev-env/var
 scratch/
 compiler/daml-extension/node_modules/

BAZEL.md

@@ -147,9 +147,8 @@ plugin referencing [ij.bazel.build][intellij_plugin].
 
 If the correct plugin does not exist in the list, then your IntelliJ version
 might be too recent, and the Bazel plugin might not have been upgraded to
-support it, yet. Check for version compatibility on the [Jetbrains plugin
+support it, yet. Check for version compatibility on the [JetBrains plugin
-page][intellij_plugin_jetbrains]. At the time of writing the Bazel IntelliJ
+page][intellij_plugin_jetbrains].
-plugin version 2018.10.08.0.2 has been tested on IDEA Community 2018.2.5.
 
 [intellij_plugin]: https://ij.bazel.build/
 [intellij_plugin_install]: https://ij.bazel.build/docs/bazel-plugin.html#getting-started
@@ -166,36 +165,6 @@ directories and targets to make accessible in IntelliJ and to control other
 aspects of the project. Refer to the [official
 documentation][intellij_project_view] for a detailed description.
 
-[intellij_project_view]: https://ij.bazel.build/docs/project-views.html
-
-Here we will focus on two use-cases: "Import project view file" (recommended),
-and "Generate from BUILD file".
-
-#### Import project view file
-
-Check if the project you will be working on already has a project view file.
-These are typically stored under `project/path/.bazelproject`.  If the project
-does not have a project view file yet, then you can generate one using the
-`bazel-project-view` tool in dev-env as follows:
-
-```
-bazel-project-view -o ledger/sandbox/.bazelproject ledger/sandbox
-```
-
-Choose the "Import Project View File" option and select the project view file
-that you would like to import. Then, click on "Next".
-
-The following dialog allows you to define the project name, or infer it, and
-to set the location of the project data directory. It also allows you to modify
-the imported project view file. This should not be necessary. If you do wish to
-modify the project view file, then refer to the next section for instructions.
-
-Click "Next" once you are ready. You will be able to modify the project view
-file later on as well. IntelliJ will now import the project. This process will
-take a while.
-
-#### Generate from BUILD file
-
 Choose the "Generate from BUILD file" option and select the `BUILD.bazel` file
 of the project that you will be working on. Then, click on "Next".
 
@@ -205,12 +174,16 @@ the default project view file. The default should have the following structure:
 
 ```
 directories:
-  path/to/project
+  .
+
+# Automatically includes all relevant targets under the 'directories' above
+derive_targets_from_directories: true
 
 targets:
-  //path/to/project/...:all
+  # If source code isn't resolving, add additional targets that compile it here
 
 additional_languages:
+  # Uncomment any additional languages you want supported
   # ...
 ```
 
@@ -218,35 +191,59 @@ Make sure to add Scala, or other languages that you require, to the
 `additional_languages` section. The section will be pre-populated with a list
 of comments specifying the automatically detected supported languages.
 
-Add any additional directories you would like accessible in the directory tree
+If you'd like to work with all directories, we recommend the following project
-to the `directories` section.
+view configuration, which stops IntelliJ from indexing the Bazel cache, and
+avoids rebuilding the documentation:
 
-The default value in the `targets` section is a wild-card to select all project
+```
-and sub-project targets. Note that wild-cards will not automatically generate
+directories:
-*run configurations*. Run configurations are required to build targets or run
+  .
-tests from within IntelliJ. The details are explained below.
+  -docs
+
+# Automatically includes all relevant targets under the 'directories' above
+derive_targets_from_directories: true
+
+targets:
+  # If source code isn't resolving, add additional targets that compile it here
+
+additional_languages:
+  javascript
+  python
+  scala
+  typescript
+```
+
+However, you can also provide an allowed list of directories for a faster
+experience.
 
 If you wish to define a specific set of targets to work, then you can list
-these in the `targets` section.
+these in the `targets` section. This is not usually necessary, as they
+will be derived automatically.
 
-After these modifications the project view file might look like this:
+If you choose to limit the directories, you might end up with a project view
+file looking like this:
 
 ```
 directories:
   ledger/sandbox
-  ...
+  # ...
+
+# Automatically includes all relevant targets under the 'directories' above
+derive_targets_from_directories: true
 
 targets:
-  //ledger/sandbox:sandbox
+  # If source code isn't resolving, add additional targets that compile it here
-  ...
 
 additional_languages:
   scala
 ```
 
 Click "Next" once you are ready. You will be able to modify the project view
-file later on as well. IntelliJ will now import the project. This process will
+file whenever you like, so don't worry too much.
-take a while.
+ 
+IntelliJ will now import the project. This process will take a while.
+
+[intellij_project_view]: https://ij.bazel.build/docs/project-views.html
 
 ### Overview over Bazel IntelliJ Integration
 

dev-env/bin/bazel-project-view

@@ -1,76 +0,0 @@
-#!/usr/bin/env bash
-set -eo pipefail
-
-USAGEMSG="USAGE: $0 [-o OUTPUT] PROJECT
-
-Generate a default project view file for the specified Bazel package for the
-IntelliJ Bazel plugin. PROJECT must be a valid Bazel package without the
-leading '//'. For example 'ledger-client/ods'.
-
-Example usage:
-
-    bazel-project-view -o ledger-client/ods/.bazelproject ledger-client/ods
-
-"
-
-usage() {
-    echo "$USAGEMSG"
-    exit $1
-}
-
-OUTPUT="-"
-while getopts "ho:" flag; do
-  case "$flag" in
-    h)
-      usage 0
-      ;;
-    o)
-      OUTPUT="$OPTARG"
-      ;;
-    *)
-      usage 1
-      ;;
-    esac
-done
-shift $((OPTIND-1))
-
-if [[ $# -ne 1 ]]; then
-    usage 1
-fi
-
-PROJECT="$1"
-
-# Run Bazel query, return results sorted and indented.
-query() {
-  bazel query "$1" | sort | sed 's/^/  /'
-}
-
-echo "Querying library targets..." >&2
-LIB_TARGETS="$(query 'kind("library rule", //'"$PROJECT"'/...)')"
-echo "Querying test targets..." >&2
-TEST_TARGETS="$(query 'tests(//'"$PROJECT"'/...)')"
-echo "Querying executable targets..." >&2
-EXE_TARGETS="$(query 'kind("binary rule", //'"$PROJECT"'/...)')"
-
-PROJET_VIEW="directories:
-  $PROJECT
-
-targets:
-  # Library targets
-$LIB_TARGETS
-
-  # Test targets
-$TEST_TARGETS
-
-  # Executable targets
-$EXE_TARGETS
-
-additional_languages:
-  scala
-"
-
-if [[ "$OUTPUT" == "-" ]]; then
-  echo "$PROJET_VIEW"
-else
-  echo "$PROJET_VIEW" > "$OUTPUT"
-fi