Documentation... and refactoring (#517)

* Major dev documentation update
* Refactor: Simplify LegBusSet
* Refactor: renaming of LegBusSet/HorizontalBusLane/LBSCluster/VBSClusterSide to VerticalBusSet/HorizontalBusList/BSCluster/BSClusterSide
* Refactor: renaming PositionFromExtension into PositionPredefined 
* Refactor: create new packages layout.position, layout.position.clustering and layout.position.predefined: new packages to separate the PositionFinder implementations from the rest of the layout package
* Refactor: Clarify PositionFinder interface by transferring some of particulars methods to AbstractPositionFinder
* Refactor: HorizontalBusListManager functional interface is now directly within PositionPredefined and PositionByClustering which should reduce the complexity...
* Refactor: Remove cyclic dependency between Links and BSClusterSide.

single-line-diagram/single-line-diagram-cgmes/single-line-diagram-cgmes-layout/src/main/java/com/powsybl/sld/cgmes/layout/LayoutToCgmesDlExporterTool.java

@@ -15,8 +15,8 @@
 import com.powsybl.sld.cgmes.dl.conversion.CgmesDLExporter;
 import com.powsybl.sld.cgmes.dl.conversion.CgmesDLUtils;
 import com.powsybl.sld.layout.*;
-import com.powsybl.sld.layout.positionbyclustering.PositionByClustering;
-import com.powsybl.sld.layout.positionfromextension.PositionFromExtension;
+import com.powsybl.sld.layout.position.clustering.PositionByClustering;
+import com.powsybl.sld.layout.position.predefined.PositionPredefined;
 import com.powsybl.tools.Command;
 import com.powsybl.tools.Tool;
 import com.powsybl.tools.ToolOptions;
@@ -46,7 +46,7 @@ public class LayoutToCgmesDlExporterTool implements Tool {
     private static final String DIAGRAM_NAME = "diagram-name";
 
     private final Map<String, VoltageLevelLayoutFactory> voltageLevelsLayouts
-            = Map.ofEntries(Map.entry("auto-extensions", new PositionVoltageLevelLayoutFactory(new PositionFromExtension())),
+            = Map.ofEntries(Map.entry("auto-extensions", new PositionVoltageLevelLayoutFactory(new PositionPredefined())),
             Map.entry(DEFAULT_VOLTAGE_LAYOUT, new PositionVoltageLevelLayoutFactory(new PositionByClustering())));
 
     private final Map<String, SubstationLayoutFactory> substationsLayouts

single-line-diagram/single-line-diagram-cgmes/single-line-diagram-cgmes-layout/src/main/java/com/powsybl/sld/cgmes/layout/LayoutToCgmesExtensionsConverter.java

@@ -12,7 +12,7 @@
 import com.powsybl.sld.cgmes.dl.conversion.CgmesDLUtils;
 import com.powsybl.sld.cgmes.dl.iidm.extensions.*;
 import com.powsybl.sld.layout.*;
-import com.powsybl.sld.layout.positionbyclustering.PositionByClustering;
+import com.powsybl.sld.layout.position.clustering.PositionByClustering;
 import com.powsybl.sld.library.ComponentTypeName;
 import com.powsybl.sld.model.coordinate.Orientation;
 import com.powsybl.sld.model.graphs.*;

single-line-diagram/single-line-diagram-core/doc/BSCluster.adoc

@@ -0,0 +1,43 @@
+= `BSCluster`
+
+== Definition
+`BSCluster` (`BusNode` Sets Cluster) are used by implementations of `PositionFinder`.
+
+****
+It is composed of 2 kinds of sets of `BusNode` Sets that present an horizontal and a vertical view of the structure of a `VoltageLevel`:
+
+- `List<VerticalBusSet> verticalBusSets` see link:VerticalBusSet.adoc[VerticalBusSet]
+- `List<HorizontalBusList> horizontalBusLists` see link:HorizontalBusList.adoc[HorizontalBusList]
+****
+
+
+[IMPORTANT]
+====
+`VerticalBusSet` is a `Set` as it is important to have no duplicate `BusNodes` whereas, it is possible to have duplicate `BusNodes` in the `HorizontalBusList`.
+
+The rules are as follow: 
+
+- for `VerticalBusSet`, a `BusNode` may appear:
+* in multiple `VerticalBusSets`,
+* but only once in a `VerticalBusSet`;
+- for `HorizontalBusList`, a `BusNode` may appear:
+* multiple times in a `HorizontalBusList`, in that case the occurences shall have contiguous indexes,
+* shall appear only in one single `HorizontalBusList`.
+====
+
+The goal is at the end to be able to merge the `VoltageLevel` into a single `BSCluster` having to this kind of pattern:
+
+image::images/BSClusterFinal.svg[align="center"]
+
+== Key methods
+
+=== Build
+A `BSCluster` is initiated with one `VerticalBusSet` that:
+
+- is put as is as first element `verticalBusSets`,
+- inititiates one `HorizontalBusList` for each of its `BusNode`
+
+Each `PositionFinder` using `BSCluster` implementation provides a strategy to merge them together in order to get a single `BSCluster`.
+
+=== Merge
+The merge of 2 `BSClusters` is done by calling the `merge` method giving it a `HorizontalBusListManager`. Indeed if the merging of the `verticalBusSets` is just a concatenation, the merging of the `horizontalBusLists` differs from one `PositionFinder` to another.

single-line-diagram/single-line-diagram-core/doc/CellDetector.adoc

@@ -121,8 +121,3 @@ Last, the second `ExternCell` cell is build with the second `SHUNT` node and the
 
 .Descrimination of a `SHUNT` cell
 image::images/rawGraphExternShunt.svg[align="center"]
-
-'''
-==== The `PatternCellDetector` class
-
-This detector is based on pattern matching algorithm. The patterns are described in `/resources/pattern.xml`.

single-line-diagram/single-line-diagram-core/doc/HorizontalBusList.adoc

@@ -0,0 +1 @@
+= `HorizontalBusList`