Clean documentation (powsybl#3731)

Clean documentation (powsybl#3731)

* Rearrange itools documentation pages (fix links, create itools 'commands' section)
* Clean excluded page from the generation + configure link to pypowsybl documentation
* Clean itools modules pages, complete the configuraion part of the loadflow and security analysis regarding the module configuration
* Some fixes among links to guide the user
* Add itools-packager and itools plugins-info command documentation
* Add link to powsybl-tutorial to create IIDM Importer/Exporter
* Add network module
* Add table-formatter module
* Add itools usages examples in the documentation
* Fix some documentation compilation errors
* Handle feedbacks

---------

Signed-off-by: CARON Alice <alice.caron@rte-france.com>
Signed-off-by: Thomas Bouquet <thomas.bouquet@rte-france.com>

Author: alicecaron

docs/conf.py

@@ -86,7 +86,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md']
 
 # Reference sections generation
 autosectionlabel_prefix_document = True
@@ -131,7 +131,8 @@
     "powsyblopenloadflow": ("https://powsybl.readthedocs.io/projects/powsybl-open-loadflow/en/latest/", None),
     "powsybldynawo": ("https://powsybl.readthedocs.io/projects/powsybl-dynawo/en/latest/", None),
     "powsybldiagram": ("https://powsybl.readthedocs.io/projects/powsybl-diagram/latest/", None),
-    "powsybltutorials": ("https://powsybl.readthedocs.io/projects/powsybl-tutorials/en/latest/", None)
+    "powsybltutorials": ("https://powsybl.readthedocs.io/projects/powsybl-tutorials/en/latest/", None),
+    "pypowsybl": ("https://powsybl.readthedocs.io/projects/pypowsybl/en/latest/", None)
 }
 intersphinx_disabled_reftypes = ["*"]
 

docs/grid_exchange_formats/cgmes/export.md

@@ -477,7 +477,7 @@ PowSyBl [`VoltageLevel`](../../grid_model/network_subnetwork.md#voltage-level) i
 (cgmes-control-areas-export)=
 ### Control areas
 
-PowSyBl [`ControlAreas`](import.md#cgmes-control-areas) are exported as several `ControlArea`.
+PowSyBl [`ControlAreas`](import.md#control-areas) are exported as several `ControlArea`.
 
 <span style="color: red">TODO details</span>
 

docs/grid_exchange_formats/cgmes/import.md

@@ -136,7 +136,7 @@ The mapping of an `EquivalentInjection` depends on its location relative to the
 
 If the `EquivalentInjection` is outside the boundary area, it will be mapped to a PowSyBl `Generator`.
 
-If the `EquivalentInjection` is at the boundary area, its regulating voltage data will be mapped to the generation data inside the PowSyBl `DanglingLine` created at the boundary point and its values for `P`, `Q` will be used to define the DanglingLine `P0`, `Q0`. Please note that the said `DanglingLine` can be created from an [`ACLineSegment`](#aclinesegment), a [`Switch`](#switch-switch-breaker-disconnector-loadbreakswitch-protectedswitch-grounddisconnector),
+If the `EquivalentInjection` is at the boundary area, its regulating voltage data will be mapped to the generation data inside the PowSyBl `DanglingLine` created at the boundary point and its values for `P`, `Q` will be used to define the DanglingLine `P0`, `Q0`. Please note that the said `DanglingLine` can be created from an [`ACLineSegment`](#aclinesegment), a [`Switch`](#switch-switch-breaker-disconnector-loadbreakswitch-protectedswitch-grounddisconnector-jumper),
 an [`EquivalentBranch`](#equivalentbranch) or a [`PowerTransformer`](#powertransformer).
 
 Attributes of the PowSyBl generator or of the PowSyBl dangling line generation are created as such:

docs/grid_exchange_formats/iidm/export.md

@@ -20,20 +20,20 @@ The `iidm.export.xml.anonymised` property is an optional property that defines w
 
 **iidm.export.xml.topology-level**<br>
 The `iidm.export.xml.topology-level` property is an optional property that defines the most detailed topology in which the XIIDM exporter can export the network. The topology level can be:
-- `NODE_BREAKER`: the voltage levels are exported using the [Node/Breaker view](). Voltage levels described in Bus/Breaker topology are exported using the [Bus/Breaker view]().
-- `BUS_BREAKER`: all voltage levels are all exported using the [Bus/Breaker view]()
-- `BUS_BRANCH`:  all voltage levels are exported using the [Bus view]()
+- `NODE_BREAKER`: the voltage levels are exported using the Node/Breaker view. Voltage levels described in Bus/Breaker topology are exported using the Bus/Breaker view.
+- `BUS_BREAKER`: all voltage levels are all exported using the Bus/Breaker view
+- `BUS_BRANCH`:  all voltage levels are exported using the Bus view
 
 The default value is `NODE_BREAKER` to export all voltage levels in the same level of details than the one they are described.
 
 **iidm.export.xml.topology-level.voltage-levels.node-breaker**<br>
-The `iidm.export.xml.topology-level.voltage-levels.node-breaker` property is an optional property that defines a list of voltage level IDs to be exported using the [Node/Breaker view]() by the IIDM exporter. Note: if the voltage level is described using a lower detailed topology (Bus/Breaker or Bus/Branch), it will be exported using the Bus/Breaker (or Bus/Branch) view (Node/Breaker is not possible since the voltage level has not enough details).
+The `iidm.export.xml.topology-level.voltage-levels.node-breaker` property is an optional property that defines a list of voltage level IDs to be exported using the Node/Breaker view by the IIDM exporter. Note: if the voltage level is described using a lower detailed topology (Bus/Breaker or Bus/Branch), it will be exported using the Bus/Breaker (or Bus/Branch) view (Node/Breaker is not possible since the voltage level has not enough details).
 
 **iidm.export.xml.topology-level.voltage-levels.bus-breaker**<br>
-The `iidm.export.xml.topology-level.voltage-levels.bus-breaker` property is an optional property that defines a list of voltage level IDs to be exported using the [Bus/Breaker view]() by the IIDM exporter.
+The `iidm.export.xml.topology-level.voltage-levels.bus-breaker` property is an optional property that defines a list of voltage level IDs to be exported using the Bus/Breaker view by the IIDM exporter.
 
 **iidm.export.xml.topology-level.voltage-levels.bus-branch**<br>
-The `iidm.export.xml.topology-level.voltage-levels.bus-branch` property is an optional property that defines a list of voltage level IDs to be exported using the [Bus/Branch view]() by the IIDM exporter.
+The `iidm.export.xml.topology-level.voltage-levels.bus-branch` property is an optional property that defines a list of voltage level IDs to be exported using the Bus/Branch view by the IIDM exporter.
 
 **iidm.export.xml.throw-exception-if-extension-not-found**<br>
 The `iidm.export.xml.throw-exception-if-extension-not-found` property is an optional property that defines whether the XIIDM exporter throws an exception if the network contains an unknown or unserializable extension or if it just ignores it. Its default value is `false`.

docs/grid_features/extraction.md

@@ -205,9 +205,7 @@ reducer.reduce(network)
 saveNetwork("XIIDM", network, null, args[1])
 ```
 
-See the [groovy scripts]() documentation page for more information about this topic.
-
-Then, we run the [groovy-script]() command to apply the previous script to the `network.xiidm` file, and then export the modified network to the `network2.xiidm` file.
+Then, we run the [groovy-script](../user/itools/run-script.md) command to apply the previous script to the `network.xiidm` file, and then export the modified network to the `network2.xiidm` file.
 ```shell
 $> ./itools run-script --file extraction.groovy network.xiidm network2.xiidm
 ```

docs/grid_features/loadflow_validation.md

@@ -4,6 +4,8 @@ A load flow result is considered *acceptable* if it describes a feasible steady-
 More practically, generations of practitioners have set quasi-standard ways to describe them that makes it possible to define precise rules.
 They are described below for the different elements of the network.
 
+See the documentation [here](../user/configuration/loadflow-validation.md) to configure correctly this module.
+
 (loadflow-validation-buses)=
 ## Buses
 

docs/grid_features/network_modifications.md

@@ -46,11 +46,11 @@ It takes as input:
 - The ID of the bus or busbar section (in `BUS_BREAKER` or `NODE_BREAKER` voltage levels respectively) to which the
   injection should be connected.
 - The position order of the injection: when adding an injection to a `NODE_BREAKER` voltage level, this integer will be
-  used to create the [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position-extension) that is
+  used to create the [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position) that is
   used for visualization. It is optional for `BUS_BREAKER` voltage levels and will be ignored if specified.
-- Optionally, a name for the [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position-extension).
+- Optionally, a name for the [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position).
   By default, the ID of the injection will be used.
-- Optionally, the direction of the injection. It is also used to fill the [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position-extension).
+- Optionally, the direction of the injection. It is also used to fill the [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position).
   It indicates if the injection should be displayed at the top or at the bottom of the busbar section. By default, it is
   `BOTTOM`.
 - Optionally, a boolean `logOrThrowIfIncorrectPositionOrder`, that indicates what should happen if the position order is
@@ -71,8 +71,8 @@ If the voltage level topology kind is `BUS_BREAKER`, then the injection is added
 bus without any extension or switches.
 If the voltage level topology kind is `NODE_BREAKER`, then the injection is added to the voltage level and connected to
 the busbar section with a closed disconnector and a breaker. Additionally, open disconnectors will be created on every
-parallel busbar section. To know which busbar sections are parallel, the [`BusbarSectionPosition` extension](../grid_model/extensions.md#busbar-section-position-extension)
-is used. The [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position-extension) will also be
+parallel busbar section. To know which busbar sections are parallel, the [`BusbarSectionPosition` extension](../grid_model/extensions.md#busbar-section-position)
+is used. The [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position) will also be
 created for the injection with the given data, unless there are no extensions yet in the voltage level.
 
 #### Create Branch Feeder bays
@@ -84,15 +84,15 @@ It takes as input:
 - The ID of the bus or busbar section (in `BUS_BREAKER` or `NODE_BREAKER` voltage levels respectively) to which the side
   2 of the branch should be connected.
 - The position order of the branch on side 1. If the voltage level on side 1 of the branch is `NODE_BREAKER`, then
-  this integer is used to create the [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position-extension)
+  this integer is used to create the [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position)
   for the branch that is used for visualization and for positioning connectables relative to each other.
   It is optional for `BUS_BREAKER` voltage levels and will be ignored if specified.
 - The position order of the branch on side 2. It is the same but on the other side.
-- Optionally, a name for the feeder that will be added in the [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position-extension)
+- Optionally, a name for the feeder that will be added in the [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position)
   for side 1. This name is used for visualization. By default, it is the ID of the connectable.
 - Optionally, a name for the feeder for side 2.
 - Optionally, the direction of the feeder on side 1. This information will be used to fill the field in the
-  [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position-extension) and indicates the relative
+  [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position) and indicates the relative
   position of the branch with its busbar section on side 1. The default value is `TOP`.
 - Optionally, the direction on side 2.
 - Optionally, a boolean `logOrThrowIfIncorrectPositionOrder1`, that indicates what should happen if the position order is
@@ -114,8 +114,8 @@ For each side, if the voltage level topology kind is `BUS_BREAKER`, then the bra
 connected to the bus without any extension or switches. If the voltage level topology kind is `NODE_BREAKER`, then the
 branch is added to the voltage level and connected to the busbar section with a closed disconnector and a breaker.
 Additionally, open disconnectors will be created on every parallel busbar section. To know which busbar sections are
-parallel, the [`BusbarSectionPosition` extension](../grid_model/extensions.md#busbar-section-position-extension)
-is used. The [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position-extension) will also be
+parallel, the [`BusbarSectionPosition` extension](../grid_model/extensions.md#busbar-section-position)
+is used. The [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position) will also be
 created for the branch with the given data, unless no extensions are already available in the voltage level.
 
 #### Create Coupling Device
@@ -133,7 +133,7 @@ busbar sections as such:
 A closed disconnector will be created on both busbar sections.
 A closed breaker will be created between the two closed disconnectors.
 An open disconnector will be created on every parallel busbar section. To find the parallel busbar sections, the
-[`BusbarSectionPosition` extension](../grid_model/extensions.md#busbar-section-position-extension) is used.
+[`BusbarSectionPosition` extension](../grid_model/extensions.md#busbar-section-position) is used.
 The coupling device can be created between busbar sections that are parallel or not. If the two busbar sections are
 parallel and there are exactly two parallel busbar sections, then no open disconnectors are created.
 
@@ -199,7 +199,7 @@ It takes as input:
 
 ### Connect feeders to busbar sections
 This class allows the connection of feeders to busbar sections in `NODE_BREAKER` topology.
-The [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position-extension) must be available for each busbar section in the voltage level.
+The [`ConnectablePosition` extension](../grid_model/extensions.md#connectable-position) must be available for each busbar section in the voltage level.
 
 It takes as input:
 - A list of connectables that should be connected. None of them should be a `BusbarSection`.

docs/grid_model/extensions.md

@@ -13,7 +13,7 @@ Every extension is considered as serializable unless explicitly specified as non
 
 (active-power-control-extension)=
 ## Active power control
-This extension is used to configure the participation factor of the generator, typically in the case of a load flow computation with distributed slack enabled (with [balance type](../simulation/loadflow/configuration.md#generic-parameters) on generator). This extension is attached to a [generator](network_subnetwork.md#generator) or a [battery](network_subnetwork.md#battery).
+This extension is used to configure the participation factor of the generator, typically in the case of a load flow computation with distributed slack enabled (with [balance type](../simulation/loadflow/configuration.md#optional-properties) on generator). This extension is attached to a [generator](network_subnetwork.md#generator) or a [battery](network_subnetwork.md#battery).
 
 | Attribute            | Type    | Unit                   | Required | Default value | Description                                                                           |
 |----------------------|---------|------------------------|----------|---------------|---------------------------------------------------------------------------------------|
@@ -610,9 +610,9 @@ This extension is used for generators with a remote reactive control.
 This extension is attached to a [voltage level](network_subnetwork.md#voltage-level) and is used to define the slack bus
 of a power flow calculation i.e. which bus will be used to balance the active and reactive power in load flow analysis.
 Use this extension before a computation to force the slack bus selection. You should enable default load flow parameter
-[`isReadSlackBus`](../simulation/loadflow/configuration.md#generic-parameters). Use this extension after a computation to attach
+[`readSlackBus`](../simulation/loadflow/configuration.md#optional-properties). Use this extension after a computation to attach
 to the network the slack bus that has been selected by the load flow engine (one by connected component). You should enable
-default load flow parameter [`isWriteSlackBus`](../simulation/loadflow/configuration.md#generic-parameters).
+default load flow parameter [`writeSlackBus`](../simulation/loadflow/configuration.md#optional-properties).
 
 The slack bus is defined through the terminal of a connectable that belongs to the bus. It is totally allowed to define a disconnected terminal as slack as the connectable could be reconnected during a grid study.
 

docs/index.md

@@ -5,7 +5,7 @@ PowSyBl (<b>Pow</b>er <b>Sy</b>stem <b>Bl</b>ocks) is an open source library wri
 dedicated to electrical grid modeling, simulation and visualization, licensed under the [Mozilla Public License version 2.0](https://www.mozilla.org/en-US/MPL/2.0/).
 It is part of [LF Energy](https://www.lfenergy.org/), an open source foundation focused on the energy sector, hosted within The Linux Foundation.
 
-PowSyBl is used through Python scripts using the library [Pypowsybl](https://powsybl.readthedocs.io/projects/pypowsybl/en/stable/), but also
+PowSyBl is used through Python scripts using the library [Pypowsybl](inv:pypowsybl:*:*#index), but also
 to build state-of-the-art applications.
 
 Check the [Getting started](./user/index.md) and [Configuration](./user/configuration/index.md) pages to learn how to install and configure PowSyBl.

docs/simulation/dynamic/configuration.md

@@ -1,10 +1,15 @@
 # Configuration
 
+The `dynamic-simulation` module is used to configure the execution of the [dynamic-simulation](../../user/itools/dynamic-simulation.md) command and simulation.
+
 ## Implementation
 If you have several implementations in your classpath, you need to choose which implementation to use in your configuration file with the `default-impl-name` property.
 Each implementation is identified by its name, that may be unique in the classpath:
 - Use "Dynawo" to use powsybl-dynawo implementation
 
+The `com.powsybl.dynamicsimulation.DynamicSimulationParameters` class provides the generic parameters for all `com.powsybl.dynamicsimulation.DynamicSimulation`
+implementations. Specific parameters should be provided as an extension of the `DynamicSimulationParameters` class.
+
 **YAML configuration:**
 ```yaml
 dynamic-simulation:
@@ -55,7 +60,7 @@ This property specifies the directory path where debug files will be dumped. If
 
 ### Specific parameters
 Some implementations use specific parameters that can be defined in the configuration file or in the JSON parameters file:
-- [Dynawo](inv:powsybldynawo:*:*#dynamic_simulation/configuration)
+- [Dynawo](inv:powsybldynawo:*:*#dynamic_simulation/configuration) and its default parameters.
 
 ### Examples