Moved IntelliJ wiki documentation to RTFD.

source/dev/internals/intellij/bindings.md

@@ -28,9 +28,9 @@ bind(IMyInterface.class).to(MyClass.class).in(Singleton.class);
 
 ---
 
-In some cases the class is not created by Guice but by IntelliJ IDEA's extension
-system or by the Java service provider. In that case you have to inject your
-dependencies like this:
+In some cases the class is not created by Guice but by IntelliJ IDEA's
+[extension system][6] or by the [Java service loader][7]. In that case you have
+to inject your dependencies like this:
 
 ```java
 public final class MyClass implements IMyInterface {
@@ -179,3 +179,5 @@ public final class MyClass implements IMyInterface {
 [3]: https://github.com/metaborg/spoofax-intellij/blob/develop/org.metaborg.intellij/src/main/java/org/metaborg/intellij/logging/MetaborgLoggerTypeListener.java
 [4]: https://github.com/metaborg/spoofax-intellij/blob/develop/org.metaborg.intellij/src/main/java/org/metaborg/intellij/logging/Slf4JLoggerTypeListener.java
 [5]: https://github.com/metaborg/spoofax-intellij/blob/develop/org.metaborg.intellij/src/main/java/org/metaborg/intellij/logging/LoggerUtils.java
+[6]: http://www.jetbrains.org/intellij/sdk/docs/basics/plugin_structure/plugin_extensions_and_extension_points.html
+[7]: https://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoader.html

source/dev/internals/intellij/idea-plugin.rst

@@ -0,0 +1,23 @@
+====================
+IntelliJ IDEA Plugin
+====================
+
+The IntelliJ IDEA plugin is responsible for integrating the Spoofax languages
+in IntelliJ IDEA. It provides the editor functionality (e.g. syntax
+highlighting), dialogs and wizards (e.g. New Project dialog) using the IntelliJ
+IDEA OpenAPI.
+
+Initialization
+==============
+When the plugin is loaded, a singleton instance of the `IdeaPlugin`_ application
+component is created by IntelliJ. This loads the Guice dependency injector.
+
+Bindings
+========
+The Guice bindings for the plugin can be found in the `IdeaSpoofaxModule`_
+and `IdeaSpoofaxMetaModule`_ classes. See :doc:`bindings` for more information
+on how to use Guice bindings.
+
+.. _`IdeaPlugin`: https://github.com/metaborg/spoofax-intellij/blob/develop/src/main/java/org/metaborg/spoofax/intellij/idea/IdeaPlugin.java
+.. _`IdeaSpoofaxModule`: https://github.com/metaborg/spoofax-intellij/blob/develop/org.metaborg.intellij/src/main/java/org/metaborg/intellij/idea/IdeaSpoofaxModule.java
+.. _`IdeaSpoofaxMetaModule`: https://github.com/metaborg/spoofax-intellij/blob/develop/org.metaborg.intellij/src/main/java/org/metaborg/intellij/idea/IdeaSpoofaxMetaModule.java

source/dev/internals/intellij/index.rst

@@ -1,12 +1,18 @@
 ==============================
 Intellij IDEA Plugin Internals
 ==============================
+The Spoofax plugin for IntelliJ IDEA consists of two main parts: the IntelliJ
+IDEA plugin and the JPS build plugin. They are separate plugins that are run
+in separate processes and have separate Guice bindings, but since they share
+a lot of code they live in the same project.
 
 .. toctree::
    :maxdepth: 1
 
-   overview
+   idea-plugin
+   jps-plugin
    bindings
+   dependencies
    logging
    vfs
    configurations

source/dev/internals/intellij/jps-plugin.rst

@@ -0,0 +1,63 @@
+==========
+JPS Plugin
+==========
+
+The JPS build plugin is responsible for building a Spoofax language
+specification or Spoofax-enabled project. It's loaded in a separate process
+by IntelliJ IDEA when the user executes the *Make* action.
+
+
+Initialization
+==============
+When the plugin is loaded, the static members of the `JpsPlugin`_ class are
+initialized. This loads the Guice dependency injector.
+
+
+Bindings
+========
+The Guice bindings for the plugin can be found in the `JpsSpoofaxModule`_
+and `JpsSpoofaxMetaModule`_ classes. See :doc:`bindings` for more information
+on how to use Guice bindings.
+
+
+Deserialization
+===============
+The JPS plugin has an internal representation of the project, its modules,
+files, settings, facets, SDK, and so on, in the `JpsModel`_ class.
+
+When the JPS plugin is run, IntelliJ creates a JPS model that reflects the
+IntelliJ project structure. However, IntelliJ has no knowledge of any special
+extensions and settings that we have applied to the IntelliJ project. We need
+to update the JPS model with our own information where needed. This is done
+through the deserializers returned from the
+`JpsSpoofaxModelSerializerExtension`_ class.
+
+
+Gathering build targets
+=======================
+A *build target* is a single compilation unit. JPS now gathers all build targets
+that can apply to the model, and orders them according to their dependencies.
+
+The `BuilderService`_ advertises which build target *types* we have implemented.
+Each `BuildTargetType<T>`_ implementation then decides which build targets we
+have. Usually every module that we can compile gets its own `BuildTarget<T>`_.
+
+
+Building
+========
+Our `BuilderService`_ also advertised which *target builders* we have. Every
+`TargetBuilder<T, U>`_ has a ``build()`` method that's executed for every
+appropriate build target.
+
+
+
+
+.. _`JpsPlugin`: https://github.com/metaborg/spoofax-intellij/blob/develop/src/main/java/org/metaborg/spoofax/intellij/jps/JpsPlugin.java
+.. _`JpsSpoofaxModule`: https://github.com/metaborg/spoofax-intellij/blob/develop/org.metaborg.intellij/src/main/java/org/metaborg/intellij/jps/JpsSpoofaxModule.java
+.. _`JpsSpoofaxMetaModule`: https://github.com/metaborg/spoofax-intellij/blob/develop/org.metaborg.intellij/src/main/java/org/metaborg/intellij/jps/JpsSpoofaxMetaModule.java
+.. _`JpsModel`: https://github.com/JetBrains/intellij-community/blob/a5cd6ac6102731ea9b557dcc1c684340f7d8432a/jps/model-api/src/org/jetbrains/jps/model/JpsModel.java
+.. _`JpsSpoofaxModelSerializerExtension`: https://github.com/metaborg/spoofax-intellij/blob/develop/src/main/java/org/metaborg/spoofax/intellij/jps/JpsSpoofaxModelSerializerExtension.java>) class. They deserialize the information serialized by the IntelliJ plugin classes that implement [`PersistentStateComponent<T>`](<https://github.com/JetBrains/intellij-community/blob/a5cd6ac6102731ea9b557dcc1c684340f7d8432a/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java
+.. _`BuilderService`: https://github.com/metaborg/spoofax-intellij/blob/develop/src/main/java/org/metaborg/spoofax/intellij/jps/SpoofaxBuilderService.java
+.. _`BuildTargetType<T>`: https://github.com/metaborg/spoofax-intellij/blob/develop/src/main/java/org/metaborg/spoofax/intellij/SpoofaxTargetType.java
+.. _`BuildTarget<T>`: https://github.com/metaborg/spoofax-intellij/blob/develop/src/main/java/org/metaborg/spoofax/intellij/SpoofaxTarget.java
+.. _`TargetBuilder<T, U>`: https://github.com/metaborg/spoofax-intellij/blob/develop/src/main/java/org/metaborg/spoofax/intellij/jps/SpoofaxBuilder.java

source/langdev/manual/env/intellij/existing-language-spec.md

@@ -8,17 +8,17 @@ dialog.
 
 2. Browse to the root folder of the project, and click _OK_.
 
-   ![Browsing to the project](import_langspec.png)
+   ![Browsing to the project](img/import_langspec.png)
 
 3. Select _Create project from existing sources_ and click _Next_.
 
-   ![Browsing to the project](import_langspec_existingsources.png)
+   ![Browsing to the project](img/import_langspec_existingsources.png)
 
 4. Pick a project name, and ensure the location is correct. Click _Next_.
 
 5. Ensure both the _Java_ and _Spoofax module_ roots are checked.
 
-   ![Check the project roots](import_langspec_projectroots.png)
+   ![Check the project roots](img/import_langspec_projectroots.png)
 
 6. Click _Finish_.
 

source/langdev/manual/env/intellij/existing-project.md

@@ -10,9 +10,10 @@ can use Metaborg languages in it.
 
 3. Go to the _Facets_ tab.
 
-4. Click the ![Plus](button_plus.png) button and select _Metaborg_ from the drop-down menu.
+4. Click the ![Plus](img/button_plus.png) button and select _Metaborg_ from the
+   drop-down menu.
 
-   !["Project Structure" dialog](projectstructure_addmetaborgfacet.png)
+   !["Project Structure" dialog](img/projectstructure_addmetaborgfacet.png)
 
 5. Select the module to add the facet to, and click _OK_.
 
@@ -22,7 +23,7 @@ can use Metaborg languages in it.
 
 8. Select the _Metaborg SDK_ as the module's SDK.
 
-   ![Select the "Metaborg SDK"](projectstructure_setmetaborgsdk.png)
+   ![Select the "Metaborg SDK"](img/projectstructure_setmetaborgsdk.png)
 
    ```eval_rst
    .. include:: module-sdk.txt

source/langdev/manual/env/intellij/index.rst

@@ -2,11 +2,27 @@
 IntelliJ IDEA Environment
 =========================
 
+**Spoofax for IntelliJ IDEA** is an IntelliJ IDEA plugin for creating and
+building languages with the `Spoofax Language Workbench`_. Spoofax is a
+platform for developing textual domain-specific languages, and its language
+workbench includes tools and meta languages for defining syntax, name bindings,
+types and tree transformations, among others.
+
+
 .. toctree::
    :maxdepth: 1
 
+   installation
    new-project
    existing-project
    new-language-spec
    existing-language-spec
    load-and-unload-languages
+
+
+See also
+--------
+- :doc:`/source/dev/internals/intellij/index`
+
+
+.. _`Spoofax Language Workbench`: http://www.spoofax.org

source/langdev/manual/env/intellij/installation.md

@@ -0,0 +1,5 @@
+# Installation
+
+```eval_rst
+.. todo:: This part of the documentation has not been written yet.
+```

source/langdev/manual/env/intellij/load-and-unload-languages.md

@@ -11,9 +11,9 @@ _Settings_ dialog are loaded for every instance of the application.
 
 2. Go to the _Languages & Frameworks_ → _Metaborg Languages_ page.
 
-3. Use the ![Plus](button_plus.png) and  ![Plus](button_minus.png) buttons
-   to load or unload a language.
+3. Use the ![Plus](img/button_plus.png) and  ![Plus](img/button_minus.png)
+   buttons to load or unload a language.
 
-   ![Changing the loaded languages](settings_metaborglanguages_add.png)
+   ![Changing the loaded languages](img/settings_metaborglanguages_add.png)
 
 4. Click _OK_ to apply the changes.

source/langdev/manual/env/intellij/module-sdk.txt

@@ -2,10 +2,10 @@
    Metaborg SDK, then you need to add it first.
 
    1. Click the *New...* button next to the *Module SDK* field.
-   
+
    2. Select *Metaborg SDK*.
 
-      .. image:: projectstructure_newsdkmenu.png
+      .. image:: img/projectstructure_newsdkmenu.png
 
    3. You may get a warning if you have no Java JDK configured. Click *OK*
       and configure the JDK's home location. The suggested home

source/langdev/manual/env/intellij/new-langspec-sdk.txt

@@ -3,7 +3,7 @@
 
    1. Click the *New...* button next to the *Project SDK* field.
 
-      .. image:: newproject_langspec_newsdk.png
+      .. image:: img/newproject_langspec_newsdk.png
 
    2. You may get a warning if you have no Java JDK configured. Click *OK*
       and configure the JDK's home location. The suggested home

source/langdev/manual/env/intellij/new-language-spec.md

@@ -9,21 +9,21 @@ _Project..._ menu item, to open the _New Project_ dialog.
 
 3. Select the _Metaborg SDK_ as the project's SDK.
 
-   ![Select the "Metaborg SDK"](newprojectform_langspec_selectmetaborgsdk.png)
+   ![Select the "Metaborg SDK"](img/newprojectform_langspec_selectmetaborgsdk.png)
 
    ```eval_rst
    .. include:: new-langspec-sdk.txt
    ```
 
 4. Change the fields to suit your needs.
 
-   ![Change the fields](newprojectform_langspec_inputfields.png)
+   ![Change the fields](img/newprojectform_langspec_inputfields.png)
 
 5. Click _Next_.
 
 6. Pick a project name and location, and click _Finish_.
 
-   ![Pick a project name](newprojectform_langspec_projectname.png)
+   ![Pick a project name](img/newprojectform_langspec_projectname.png)
 
 The created Spoofax language specification project will have a `metaborg.yaml`
 file, which specifies the configuration and language dependencies of the

source/langdev/manual/env/intellij/new-project-sdk.txt

@@ -2,10 +2,10 @@
    Metaborg SDK, then you need to add it first.
 
    1. Click the *New...* button next to the *Project SDK* field.
-   
+
    2. Select *Metaborg SDK*.
 
-      .. image:: newprojectform_newsdkmenu_small.png
+      .. image:: img/newprojectform_newsdkmenu_small.png
 
    3. You may get a warning if you have no Java JDK configured. Click *OK*
       and configure the JDK's home location. The suggested home

source/langdev/manual/env/intellij/new-project.md

@@ -9,11 +9,11 @@ _Project..._ menu item, to open the _New Project_ dialog.
 
 3. Check the _Metaborg_ framework.
 
-   !["New Project" dialog](newprojectform_checkmetaborgframework.png)
+   !["New Project" dialog](img/newprojectform_checkmetaborgframework.png)
 
 4. Select the _Metaborg SDK_ as the project's SDK.
 
-   ![Select the "Metaborg SDK"](newprojectform_selectmetaborgsdk_small.png)
+   ![Select the "Metaborg SDK"](img/newprojectform_selectmetaborgsdk_small.png)
 
    ```eval_rst
    .. include:: new-project-sdk.txt
@@ -23,7 +23,7 @@ _Project..._ menu item, to open the _New Project_ dialog.
 
 6. Pick a project name and location, and click _Finish_.
 
-   ![Pick a project name](newprojectform_javaprojectname.png)
+   ![Pick a project name](img/newprojectform_javaprojectname.png)
 
 The created Java project will have the _Metaborg facet_, indicating that the
 project uses Metaborg languages. It will also have a `metaborg.yaml` file, which