Docs: New website.

Author: Christoph Daniel Schulze

docs/config.toml

@@ -0,0 +1,5 @@
+languageCode = "en-us"
+title = "Eclipse Layout Kernel"
+baseurl = "https://www.eclipse.org/elk/"
+canonifyURLs = true
+

docs/content/_index.md

@@ -0,0 +1,8 @@
+---
+title: "Bla bla bla"
+description: "Blupp blupp blupp"
+---
+
+# Eclipse Layout Kernel
+
+This is the content of the main page.

docs/content/documentation/AlgorithmDevelopers.md

@@ -0,0 +1,26 @@
+---
+title: "Algorithm Developers"
+menu:
+  main:
+    identifier: "AlgorithmDevelopers"
+    parent: Documentation
+    weight: 30
+---
+
+While the layout algorithms implemented in ELK already cover a wide range of layout styles, your particular application may have more specific requirements. In these cases, it may become necessary to implement your own layout algorithm, which is what this part of the documentation is all about.
+
+Implementing your own layout algorithm basically consists of the following steps:
+
+1. Install the _Eclipse Layout Kernel SDK_ into your Eclipse development environment.
+1. Create and configure a new Eclipse plug-in project.
+1. Create and register a `melk` file that describes your algorithm and its support of layout properties.
+1. Implement your algorithm, updating the `melk` file along the way.
+1. Debug your algorithm.
+
+Note that we have deliberately left out the part of "pulling your hair out while trying to understand which wretched detail of your complicated algorithm causes it to fail spectacularly" (we've been there...).
+
+**Before you start:**
+This section assumes that you have basic knowledge of how the _Eclipse Layout Kernel_ works. You should at least have worked through the [Graph Data Structure]({{< ref "documentation/ToolDevelopers/GraphDataStructure.md" >}}) and [Using Algorithms Directly]({{< ref "documentation/ToolDevelopers/UsingAlgorithmsDirectly.md" >}}) sections.
+
+**Once you are ready to start:**
+Use the navigation bar to the right to work your way through each of those steps.

docs/content/documentation/AlgorithmDevelopers/AlgorithmDebugging.md

@@ -0,0 +1,50 @@
+---
+title: "Algorithm Debugging"
+menu:
+  main:
+    identifier: "AlgorithmDebugging"
+    parent: "AlgorithmDevelopers"
+    weight: 50
+---
+
+The Eclipse Layout Kernel SDK provides two views built specifically for debugging your layout algorithm: the layout graph view and the execution time view.
+
+
+# Layout Graph View
+
+{{< image src="layout_graph_view.png" alt="Layout Graph View" >}}
+
+The layout graph view registers with the `DiagramLayoutEngine` to be notified whenever a layout run finishes and displays the layout graph exactly as it comes out of the layout algorithm, without any modifications applied. Use this view to check if your algorithm works and if you got the coordinate system right.
+
+Note that the layout graph view allows you to export the displayed graph as a PNG image file. It also allows you to display debug graph files (see below).
+
+Open the layout graph view by clicking _Window_ -> _Show View_ -> _Other_ and select _Layout Graph_ from the _Eclipse Diagram Layout_ category.
+
+
+# Layout Time View
+
+{{< image src="layout_time_view.png" alt="Layout Time View" >}}
+
+The layout time view registers with the `DiagramLayoutEngine` to be notified whenever a layout run finishes and displays which steps the layout run consisted of and, if enabled, how much time each step took to run. Measuring these execution times has to be explicitly enabled in the preferences:
+
+{{< image src="layout_time_view_enable.png" alt="Enabling layout time measurements" >}}
+
+Once enabled, the view displays two values for each item: the _time_ and the _local time_. The former is the amount of time spent for an item and all of its sub-items. Local time is the time spent on the item alone, without any sub-items (this value is omitted for items that do not have any sub-items, since it would be equal to the normal time value anyway).
+
+To take advantage of the layout time view, your algorithm must make proper use of the `IElkProgressMonitor` passed to it. The tree of progress monitors (and sub-monitors) is what gets displayed in the layout time view. Be sure to do something like this:
+
+```java
+monitor.begin("My rather good layout algorithm", 2);
+
+executePhase1(monitor.subTask(1));
+executePhase2(monitor.subTask(1));
+
+monitor.done();
+```
+
+Open the layout graph view by clicking _Window_ -> _Show View_ -> _Other_ and select _Layout Time_ from the _Eclipse Diagram Layout_ category.
+
+
+# Debug Files
+
+The ELK preference page (see above) contains another setting: _Debug graph output_. Enabling this will cause the `DiagramLayoutEngine` to save the layout graph just before automatic layout is run. The graphs are placed in your user folder, in a subfolder called `elk/diagram_layout_engine`. The graph files can be displayed by the layout graph view, even though that usually is not very helpful since they may not contain any valid layout data yet.

docs/content/documentation/AlgorithmDevelopers/AlgorithmImplementation.md

@@ -0,0 +1,44 @@
+---
+title: "Algorithm Implementation"
+menu:
+  main:
+    identifier: "AlgorithmImplementation"
+    parent: "AlgorithmDevelopers"
+    weight: 40
+---
+
+Once everything is set up, it is time to actually implement your algorithm. The problem your layout algorithm has to solve can be summarized as follows: given an input graph (possibly with existing coordinates), compute coordinates for all graph elements and routings for all edges (subject to layout properties the graph is annotated with) and annotate the layout graph accordingly. Note that the input graph defines the layout problem, but also carries the resulting coordinate assignment after your algorithm has executed.
+
+While developing your algorithm, you will regularly switch back and forth between doing that and changing [your metadata]({{< ref "documentation/AlgorithmDevelopers/MetadataLanguage.md">}}).
+
+
+## Your Algorithm's Main Class
+
+However many classes a layout algorithm consists of, it always provides one entry class that inherits from `AbstractLayoutProvider` and implements the single most important method for your algorithm:
+
+```java
+void layout(KNode layoutGraph, IElkProgressMonitor progressMonitor);
+```
+
+Let's go through the parameters in reverse order (because of reasons). The `progressMonitor` parameter should be used to track progress and check if the user wants to cancel the layout operation. Actually canceling when the user wants to cancel is one of those features that will help your software stand out from many other programs, so take this opportunity to shine!
+
+The `layoutGraph` parameter is more important, however. It defines the layout problem your algorithm should solve, in several ways. First, it defines the structure of the graph to be laid out: which nodes exist, how are they connected, and so on. Second, each graph element can have [layout options]({{< ref "documentation/ToolDevelopers/GraphDataStructure/LayoutOptions.md">}}) attached to it that are supposed to influence what your layout algorithm does with them. And third, each element may have pre-existing [coordinates or bend points]({{< ref "documentation/ToolDevelopers/GraphDataStructure/CoordinateSystem.md">}}) associated with it that your algorithm may want to make use of. Those existing coordinates will be overwritten by your algorithm to hold the new, computed coordinates.
+
+Note that the layout graph may contain nodes that themselves contain further nodes. By default, layout algorithms are only supposed to compute coordinates for the direct children of the `layoutGraph` and then set the size for the `layoutGraph` itself. However, if your layout algorithm supports hierarchical layout, and if hierarchical layout is requested (which is done through the `CoreOptions.HIERARCHY_HANDLING` layout option), you will also compute coordinates for children of children.
+
+There are two more methods your algorithm can, but does not have to implement:
+
+* `void initialize(String parameter);`
+
+    This method can be used to initialize data structures and prepare things. This method is called exactly once when an instance of your `AbstractLayoutProvider` subclass is created. Note that a single instance of your class can be used for multiple layout runs.
+
+    The `parameter` parameter is a bit tricky. Most layout algorithms won't have any need for it, but some may adjust their behavior depending on its value. One example is our interface to the [Graphviz](http://www.graphviz.org/) library that provides different layout algorithms. We only implement a single subclass of `AbstractLayoutProvider`, but each instance is passed a parameter value that indicates which of the Graphviz algorithms it will execute when the `layout(...)` method is called. Of course, which parameter to pass must be defined in [your metadata file]({{< ref "documentation/AlgorithmDevelopers/MetadataLanguage.md">}}).
+
+* `void dispose();`
+
+    Called before your `AbstractLayoutProvider` subclass is thrown towards the garbage collector.
+
+
+## Layout Options
+
+It is worth reiterating here that it is important which `IProperty` instance your algorithm uses to retrieve the value of a layout option set on a graph element. Since the [ELK metadata tooling]({{< ref "documentation/AlgorithmDevelopers/MetadataLanguage.md">}}) generates a separate class with a complete set of `IProperty` instances for each algorithm, it makes sense to use these instances. The reason is that using them ensures that you get the correct default values configured for your layout algorithm when accessing layout options that were not set on a graph element.

docs/content/documentation/AlgorithmDevelopers/CreatingANewProject.md

@@ -0,0 +1,36 @@
+---
+title: "Creating a New Project"
+menu:
+  main:
+    identifier: "CreatingANewProject"
+    parent: "AlgorithmDevelopers"
+    weight: 20
+---
+
+Layout algorithms are developed as _Eclipse Plug-in Projects_. There's a few things to setup to get your project ready, which is what we will work through here.
+
+{{% note title="If you have nothing better to do…" mode="info" %}}
+[This ticket](https://github.com/eclipse/elk/issues/29) is all about adding an _ELK Project Wizard_ to the ELK SDK that will help people create new layout algorithm projects that are already perfectly setup. If you want to make people's lifes better but don't know how, here's your chance!
+{{% /note %}}
+
+
+## Creating a New Plug-in
+
+Follow these steps to create a new plug-in:
+
+1. From the _File_ menu, select _New - Project..._.
+1. From the _Plug-in Development_ category, select _Plug-in Project_ and click _Next_.
+1. Configure your project's basic settings, in particular its name, and click _Next_.
+1. Configure your project's content. The _Properties_ should be somewhat sensible, but don't really matter all that much. In the _Options_ section, uncheck everything. Layout algorithm projects normally don't need an activator class, and don't normally make contributions to the UI. Also, don't create a rich client application. Click _Finish_.
+
+The _Package Explorer_ now shows a new project for your plug-in which we will configure in the next section.
+
+
+## Setting Up Your Plug-in
+
+Your plug-in needs to declare dependencies to ELK's most important plug-ins: `org.eclipse.elk.graph` (which contains the graph model that will be the input to your layout algorithm) and `org.eclipse.elk.core` (which contains the core ELK code). Follow these steps to add the dependencies:
+
+1. Open the `MANIFEST.MF` file, located in your plug-in's `META_INF` folder. The _Plug-in Manifest Editor_ will open up, which is divided into several pages that you can switch between using the controls at the bottom of the editor.
+1. Open the editor's _Dependencies_ tab.
+1. Click the left _Add..._ button to add a dependency. In the dialog that pops up, search for the `org.eclipse.elk.graph` plug-in and click _OK_.
+1. Repeat for ELK's core plug-in, `org.eclipse.elk.core`.

docs/content/documentation/AlgorithmDevelopers/GettingEclipseReady.md

@@ -0,0 +1,18 @@
+---
+title: "Getting Eclipse Ready"
+menu:
+  main:
+    identifier: "GettingEclipseReady"
+    parent: "AlgorithmDevelopers"
+    weight: 10
+---
+
+Developing layout algorithms requires you to have the _Eclipse Layout Kernel SDK_ installed in your Eclipse installation. Follow these steps to install it:
+
+1. Start Eclipse and select _Help - Install New Software..._ from the menu.
+1. In the _Work with:_ field, enter the address of our release or nightly update site, which you can find [on our Downloads page]({{< sectionref "downloads" >}}).
+1. From the _Eclipse Layout Kernel_ category, check _Eclipse Layout Kernel (Incubation) - SDK_ as well as _Eclipse Layout Kernel (Incubation) - SDK (sources)_ and click _Next_.
+1. Follow the instructions of the installation wizard, accepting all of the license agreements.
+1. Restart Eclipse.
+
+After the restart, there won't seem to be much of a difference. Because there isn't. But rest assured that your development environment is now perfectly prepared for what is about to come.