[WIP] Move sld documentation

docs/single_line_diagrams/layout/cellDetector.md

@@ -0,0 +1,93 @@
+# Cell detection
+
+A `Cell` represents a connected subgraph of nodes that participate in a common purpose.\
+
+The goal of the cell detection is to create these subgraphs that will then:
+
+* Structure the organisation of the busbar layout;
+* Be displayed according to their types.
+
+## Cell types
+
+Cells can be of one of the following enum `CellType`:
+
+- `INTERN`\
+The smallest subGraph delimited by `BUS` nodes (i.e. not including `FEEDER`) and that is not shunting `ExternCell` cells (see `SHUNT` definition below).\
+Such cells instantiate the `InternCell` subclass.  
+
+- `EXTERN`\
+The smallest subGraph delimited by `BUS` nodes and `FEEDER` nodes with at least one node having the following property: each branch extracted from this very node ends with nodes of a single `nodeType` among `BUS` or `FEEDER` or `SHUNT`.\
+Such cells instantiate the `ExternCell` subclass.  
+
+- `SHUNT`\
+A path between two `FictitiousNode` nodes of two `ExternCell` cells.\
+Such cells instantiate the `ShuntCell` subclass.  
+
+- `ARCH`\
+A path between an `ExternCell` and a `BusNode`.\
+Such cells instantiate the `ArchCell` class. \
+This type is obtained when an `ExternCell` is linked to two subsections, which cannot be displayed with the current algorithm.
+Such an `ExternCell` is then cut in an `ExternCell` only on one subsection, and in several `ArchCell`.
+
+The figure shows examples of cells of several `CellType`.  
+
+![cellType](/_static/img/cellTypes.svg)
+
+## Cell detection algorithm
+
+The `ImplicitCellDetector` class implements an algorithm sticking to the above cell type definitions.
+The `detectCell` method is used to detect cells by exploring the graph.
+
+It takes as parameter two lists of types that delimit the traversal algorithm :
+
+* `stopTypes` list: for types that end a current branch
+* `exclusionTypes` list: for types that invalidate the current subgraph.
+
+The algorithm is explained based on the following graph that would result in the figure displayed to illustrate the cellTypes enum:
+
+![rawGraph](/_static/img/rawGraph.svg)
+
+### Step 1: identify `InternCell` cells
+
+- stopTypes: BUS
+- exclusionTypes: FEEDER
+
+`InternCell` cells are easy to determine as being exclusively bordered by `BUS` nodes.
+
+![rawGraphIntern](/_static/img/rawGraphIntern.svg)
+
+### Step 2: identifies `ExternCell` cells
+
+- stopTypes: BUS, FEEDER
+- exclusionTypes: 
+
+If one node of the subgraph has each of its branches ending with one single kind of `NodeType` among `BUS` and `FEEDER`, ("_bottleneck_" node in the picture) this is an `ExternCell`.
+
+Other `ExternCell` cells could be discovered in the next steps when adding the `SHUNT NodeType`.
+
+![rawGraphExtern](/_static/img/rawGraphExtern.svg)
+
+### Step 3: discriminates `EXTERN` and `SHUNT` cells
+
+- stopTypes: 
+- exclusionTypes: BUS, FEEDER, SHUNT
+  To identify the first candidate `SHUNT` node, each `FICTITIOUS` node with more than 3 branches are visited. The expected property of the `SHUNT` node is that:
+
+. 1+ branch(s) ends with only `BUS` nodes
+. 1+ branch(s) ends with only `FEEDER` nodes
+. 1 branch is ends with `FEEDER` *and* `BUS` nodes.
+
+The branches of the first two categories constitutes the first `ExternCell` cell.
+
+Then the `SHUNT` cell is constituted of:
+
+* The first `SHUNT` node
+* The string of nodes that have only 2 adjacent nodes
+* The first node with more than 2 adjacent nodes that becomes the second `SHUNT` node
+
+Last, the second `ExternCell` cell is build with the second `SHUNT` node and the remaining nodes.
+
+![rawGraphExternShunt](/_static/img/rawGraphExternShunt.svg)
+
+
+⚠️ Any other pattern is not handled by the algorithm.

docs/single_line_diagrams/layout/graphRefiner.md

@@ -0,0 +1,14 @@
+# Graph refiner
+
+A preliminary step is done inside the `GraphRefiner` class. It performs some preprocessing on the input graph by calling several methods:
+* An _optional_ call to `Graph.substituteInternalMiddle2wtByEquipmentNodes()` to simplify the graph by substituting each internal two-winding transformers (i.e. both ends are in the same voltage level) `FeederNode` by a `EquipmentNode`, to avoid unnecessary snake lines;
+* A _systematic_ call to `GraphRefiner::handleConnectedComponents` which ensures that each connected component contains a `BusNode`: it is adding one if there is none;
+* A _systematic_ call to `Graph.substituteFictitiousNodesMirroringBusNodes()` to simplify the graph by removing `FICTITIOUS` nodes which are the only adjacent node of a `BusNode`;
+* An _optional_ call to `Graph.removeUnnecessaryConnectivityNodes()` to simplify the graph by removing redundant `FICTITIOUS` nodes;
+* An _optional_ call to `Graph.substituteSingularFictitiousByFeederNode()` to simplify the graph by replacing internal nodes with only one neighbor with a fictitious feeder node;
+* An _optional_ call to `Graph.removeFictitiousSwitchNode()` to simplify the graph by removing the fictitious switch nodes;
+* A _systematic_ call to `Graph.extendBusesConnectedToBuses()` to add 2 connectivity nodes between 2 buses that are connected to each other;
+* A _systematic_ call to `Graph.insertBusConnections` to create a connection between a bus node and its adjacent nodes;
+* A _systematic_ call to `Graph.insertHookNodesAtBuses()` to TODO
+* A _systematic_ call to `Graph.insertHookNodesAtFeeders()` to TODO
+* A _systematic_ call to `Graph.substituteNodesMirroringGroundDisconnectionComponent()` to deal with ground disconnector displaying.

docs/single_line_diagrams/layout/layout.md

@@ -1,3 +1,101 @@
 # Layouts
 
-Possible use of your own graph layout implementation
+A layout represents the way in which the elements of a graph are arranged.
+
+It is possible to use your own graph layout implementation but there are also existing layouts in powsybl-diagram, ready to use.
+
+
+## Layouts for voltage levels
+
+### Existing implementations
+
+#### PositionVoltageLevelLayout
+
+This layout positions the different elements inside a voltage level according to the following process:
+
+- [Clean the graph to have the expected patterns](graphRefiner.md)
+- [Detect the cells (intern / extern / shunt)](cellDetector.md)
+- Organize the cells into blocks
+- Calculate real coordinates of busNode and blocks connected to busbars
+
+##### The `PositionVoltageLevelLayoutFactoryParameters` class
+TODO
+
+##### The `PositionFinder` class
+TODO
+
+#### RandomVoltageLevelLayout
+
+With this layout, the graph node coordinates are randomly fixed:
+- Between 0 and `width` for the x coordinate;
+- Between 0 and `height` for the y coordinate.
+The `width` and `height` variables are provided by the user.
+
+#### CgmesVoltageLevelLayout
+
+With this layout, the elements of the graph are arranged according to the data present in the CGMES DL profile.
+
+### Choosing a `VoltageLevelLayout`
+
+The `voltageLevelLayoutFactoryCreator` attribute in the [`SldParameters`](../sld_parameters.md) class is the customization parameter to use to choose a specific `VoltageLevelLayout`.
+
+The `VoltageLevelLayoutFactoryCreator` creates a `VoltageLevelLayoutFactory` which in turn creates a `VoltageLevelLayout`.
+
+#### Choose a specific PositionVoltageLevelLayout
+
+Static methods are available in the `VoltageLevelLayoutFactoryCreator` interface to help users manipulate those objects.
+
+Some examples are shown below.
+
+__Example 1__
+
+PositionVoltageLevelLayout using default parameters:
+
+```java
+VoltageLevelLayoutFactoryCreator voltageLevelLayoutFactoryCreator = VoltageLevelLayoutFactoryCreator.newPositionVoltageLevelLayoutFactoryCreator();
+SldParameters sldParameters = new SldParameters().setVoltageLevelLayoutFactoryCreator(voltageLevelLayoutFactoryCreator);
+```
+
+__Example 2__
+
+PositionVoltageLevelLayout with a chosen [`PositionFinder`](#the-positionfinder-class):
+
+```java
+VoltageLevelLayoutFactoryCreator voltageLevelLayoutFactoryCreator = VoltageLevelLayoutFactoryCreator.newPositionVoltageLevelLayoutFactoryCreator(positionFinder);
+SldParameters sldParameters = new SldParameters().setVoltageLevelLayoutFactoryCreator(voltageLevelLayoutFactoryCreator);
+```
+
+__Example 3__
+
+PositionVoltageLevelLayout with chosen [`PositionVoltageLevelLayoutFactoryParameters`](#the-positionvoltagelevellayoutfactoryparameters-class):
+
+```java
+VoltageLevelLayoutFactoryCreator voltageLevelLayoutFactoryCreator = VoltageLevelLayoutFactoryCreator.newPositionVoltageLevelLayoutFactoryCreator(positionVoltageLevelLayoutFactoryParameters);
+SldParameters sldParameters = new SldParameters().setVoltageLevelLayoutFactoryCreator(voltageLevelLayoutFactoryCreator);
+```
+
+__Example 4__
+
+PositionVoltageLevelLayout with a chosen [`PositionFinder`](#the-positionfinder-class) and chosen [`PositionVoltageLevelLayoutFactoryParameters`](#the-positionvoltagelevellayoutfactoryparameters-class):
+
+```java
+VoltageLevelLayoutFactoryCreator voltageLevelLayoutFactoryCreator = VoltageLevelLayoutFactoryCreator.newPositionVoltageLevelLayoutFactoryCreator(positionFinder, positionVoltageLevelLayoutFactoryParameters);
+SldParameters sldParameters = new SldParameters().setVoltageLevelLayoutFactoryCreator(voltageLevelLayoutFactoryCreator);
+```
+
+#### Use the `SmartVoltageLevelLayoutFactory`
+
+The SmartVoltageLevelLayoutFactory picks the "best" `VoltageLevelLayout` according to the information available in the network.
+
+There is also a static method in the `VoltageLevelLayoutFactoryCreator` interface to help users pick the `SmartVoltageLevelLayoutFactory`:
+
+```java
+VoltageLevelLayoutFactoryCreator voltageLevelLayoutFactoryCreator = VoltageLevelLayoutFactoryCreator.newSmartVoltageLevelLayoutFactoryCreator();
+SldParameters sldParameters = new SldParameters().setVoltageLevelLayoutFactoryCreator(voltageLevelLayoutFactoryCreator);
+```
+
+## Layouts for substations
+TODO
+
+## Layouts for multi-substation graphs
+TODO

docs/single_line_diagrams/sld_parameters.md

@@ -0,0 +1,33 @@
+# Customizing single-line-diagrams
+
+The `SldParameters` class allows users to customize their single-line diagrams.
+
+## Customization options
+
+- Customize the svg rendering : see the `SvgParameters` class.
+- Customize the layout : see the `LayoutParameters` class.
+- Choose the component library : see the `ComponentLibrary` class.
+- Customize labels and decorators : see the `LabelProviderFactory` and `LabelProvider` interfaces.
+- Highlight information on the diagram : see the `LabelProviderFactory` and `LabelProvider` interfaces.
+- Choose the layout algorithm for voltage levels : see the `VoltageLevelLayoutFactoryCreator` interface.
+- Choose the layout algorithm for substations : see the `SubstationLayoutFactory` interface.
+- Choose the layout algorithm for multi-substation diagrams : see the `ZoneLayoutFactory` interface.
+
+
+## How to use it
+
+Default values are defined for each customization aspect.
+
+Users only need to define want they want to customize. On the following example, a customized `ComponentLibrary` is set, as well as a customized `StyleProvider`.
+
+```java
+SldParameters sldParameters = new SldParameters()
+        .setComponentLibrary(componentLibrary)
+        .setStyleProviderFactory(styleProviderFactory);
+```
+
+The `sldParameters` object should be then passed as an attribute to one of the `SingleLineDiagram` `draw` function. For example:
+
+```java
+SingleLineDiagram.draw(network, voltageLevelOrSubstationId, pathToSvgFile, sldParameters);
+```