adds a doc page for each widget

Signed-off-by: Christian Biasuzzi <[email protected]>

docs/conf.py

@@ -63,8 +63,8 @@
 #
 html_theme = "furo"
 
-html_title = 'TODO add project name'
-html_short_title = 'TODO add project name'
+html_title = 'pypowsybl-jupyter'
+html_short_title = 'pypowsybl-jupyter'
 
 html_logo = '_static/logos/logo_lfe_powsybl.svg'
 html_favicon = "_static/favicon.ico"

docs/index.md

@@ -5,12 +5,13 @@ maxdepth: 2
 hidden: true
 ---
 
+user_guide/index.md
 ```
 
 # pypowsybl-jupyter
-Widgets for [pypowsybl](https://github.com/powsybl/pypowsybl) in [Jupyter](https://jupyter.org) notebooks. 
+Widgets for [PyPowSyBl](https://github.com/powsybl/pypowsybl) in [Jupyter](https://jupyter.org) notebooks. 
 
-Pypowsybl-jupyter integrates the [powsybl-diagram-viewer](https://github.com/powsybl/powsybl-diagram-viewer) library and is built on [anywidget](https://github.com/manzt/anywidget/).
+Pypowsybl-jupyter integrates the [powsybl-diagram-viewer](https://github.com/powsybl/powsybl-diagram-viewer) library to display diagrams and is built on [anywidget](https://github.com/manzt/anywidget/) and [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/index.html)
 
 ## Getting started
 
@@ -30,35 +31,22 @@ If you want to build pypowsybl-jupyter from its sources, please check out the de
 
 ### Basic usage: network explorer
 
-The following code, to be run in a notebook, displays an interactive network explorer widget. 
+Paste this code into a Jupyter notebook, to display an interactive network explorer widget. 
 
 ```python
 import pypowsybl.network as pn
 from pypowsybl_jupyter import network_explorer
 
-network=pn.create_four_substations_node_breaker_network()
+network=pn.create_ieee9()
 
 network_explorer(network)
 ```
 
-You can select a voltage level from the list (or search of a specific one using the Filter) and the NAD and SLD diagrams for that voltage level will be displayed in the two "Network Area" and "Single Line" tabs, respectively. Both diagrams can be panned and zoomed.
+Through the network explorer widget you can display NAD and SLD diagrams for a voltage level, selected from the available network's voltage levels, in two dedicated tabs.
 
-####  Network Area tab
 
-The selected voltage level is the displayed NAD's center. 
+## Going further
 
-![network-explorer  NAD tab](/_static/img/network_explorer_1.png)
-
-A 'depth' slider controls the size of the sub network.
-
-#### Single Line tab
-
-![network-explorer SLD tab](/_static/img/network_explorer_2.png)
-
-By clicking on an arrow in the SLD you can navigate to another voltage level. 
-
-Switches can also be clicked, causing their status in the network to change; Please note that, currently, this action does not trigger any computation on the network  (e.g., a LF is not   automatically run on the network).
-
-
-## User guide
+For more details on pypowsybl-jupyter, please check out the [user guide](user_guide/index.md).
 
+In the [examples](https://github.com/powsybl/pypowsybl-jupyter/tree/main/examples) directory there are some notebooks demonstrating the widgets.

docs/user_guide/index.md

@@ -0,0 +1,14 @@
+# User Guide
+
+Pypowsybl-jupyter provides a library of interactive widgets for jupyter, targeted at visualizing network  diagrams generated e.g., through PyPowSyBl (network-area diagrams and single-line diagrams).
+
+This section details the available widgets.
+
+
+```{toctree}
+
+network_explorer.md
+nad_explorer.md
+sld_widget.md
+nad_widget.md
+```

docs/user_guide/nad_explorer.md

@@ -0,0 +1,37 @@
+# NAD explorer widget
+
+NAD (Network Area Diagram) explorer is interactive network explorer widget, built on pypowsybl-jupyter's NAD widget and some standard [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/index.html): select lists, tabs, etc.
+
+Through the widget, you can select multiple voltage levels from the list (or search of a specific one using the Filter) and the NAD diagram for those voltage levels will be displayed.
+
+The following code, to be run in a notebook, first creates a network, then displays the NAD explorer on it.
+
+```python
+import pypowsybl.network as pn
+from pypowsybl_jupyter import nad_explorer
+
+network=pn.pn.create_ieee57()
+
+nad_explorer(network)
+```
+
+![nad-explorer](/_static/img/nad_explorer.png)
+
+A 'depth' slider controls the size of the sub network.
+Pan and zoom features are available for the diagram.
+
+
+## Widget API
+
+Other than the target network, the NAD explorer can be customized using additional parameters:
+
+```python
+nad_explorer(network: Network, voltage_level_ids : list = None, depth: int = 0, low_nominal_voltage_bound: float = -1, high_nominal_voltage_bound: float = -1, parameters: NadParameters = None):
+```
+
+- network: the input network
+- voltage_level_ids: the starting list of VL to display. None displays all the network's VLs
+- depth: the diagram depth around the voltage level, controls the size of the sub network
+- low_nominal_voltage_bound: low bound to filter voltage level according to nominal voltage
+- high_nominal_voltage_bound: high bound to filter voltage level according to nominal voltage
+- parameters: layout properties to adjust the svg rendering for the nad

docs/user_guide/nad_widget.md

@@ -0,0 +1,48 @@
+# NAD widget
+
+NAD is an interactive widget that displays a Network Area Diagram's SVG, generated for example using the PyPowSyBl APIs, in a Jupyter notebook
+The widget allows you to pan and zoom the diagram, to focus on a specific part when the network is large.
+
+The following code, to be run in a notebook, first creates a network, then displays the NAD widget on it.
+
+```python
+import pypowsybl.network as pn
+from pypowsybl_jupyter import display_nad
+
+network = pn.create_ieee9()
+
+vlid=network.get_voltage_levels().index[2]
+nad=display_nad(network.get_network_area_diagram(voltage_level_ids=vlid, depth=3))
+display(nad)
+```
+
+![NAD widget](/_static/img/nad_1.png)
+
+## Update a NAD widget
+
+It is possible to update the widget's content through the update_nad API.
+The code below updates the nad widget already displayed, with a new depth parameter.
+
+```python
+from pypowsybl_jupyter import update_nad
+
+update_nad(nad, network.get_network_area_diagram(voltage_level_ids=vlid, depth=0))
+```
+
+## Widget API
+
+```python
+display_nad(svg, invalid_lf: bool = False) -> NadWidget
+```
+
+- svg: the input SVG, as str or class providing an svg and metadata representation
+- invalid_lf: When True the opacity style for some of the displayed info's (e.g., active and reactive power) is decreased, making them barely visible in the diagram.
+
+
+```python
+update_nad(nadwidget, svg, invalid_lf: bool = False)
+```
+
+- nadwidget: the existing widget to update
+- svg: the input NAD's SVG
+- invalid_lf: When True the opacity style for some of the displayed info's (e.g., active and reactive power) is decreased, making them barely visible in the diagram.

docs/user_guide/network_explorer.md

@@ -0,0 +1,48 @@
+# Network explorer widget
+
+Network explorer is interactive network explorer widget, built on pypowsybl-jupyter's widgets (SLD and NAD) and some standard [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/index.html): select lists, tabs, etc.
+
+Through the widget, you can select a voltage level from the list (or search of a specific one using the Filter) and the NAD and SLD diagrams for that voltage level will be displayed in the two "Network Area" and "Single Line" tabs, respectively. Both diagrams can be panned and zoomed.
+
+The following code, to be run in a notebook, first creates a network, then displays the network explorer on it.
+
+```python
+import pypowsybl.network as pn
+from pypowsybl_jupyter import network_explorer
+
+network=pn.create_four_substations_node_breaker_network()
+
+network_explorer(network)
+```
+
+##  Network Area tab
+
+The selected voltage level is the displayed NAD's center. 
+
+![network-explorer  NAD tab](/_static/img/network_explorer_1.png)
+
+A 'depth' slider controls the size of the sub network.
+
+## Single Line tab
+
+![network-explorer SLD tab](/_static/img/network_explorer_2.png)
+
+By clicking on an arrow in the SLD you can navigate to another voltage level. 
+
+Switches can also be clicked, causing their status in the network to change; Please note that, currently, this action does not trigger any computation on the network  (e.g., a LF is not   automatically run on the network).
+
+
+## Widget API
+
+Other than the target network, the Network explorer can be customized using additional parameters:
+
+```python
+network_explorer(network: Network, vl_id : str = None, depth: int = 0, high_nominal_voltage_bound: float = -1, low_nominal_voltage_bound: float = -1, nad_parameters: NadParameters = None, sld_parameters: LayoutParameters = None)
+```
+
+- vl_id: the starting VL to display. If None, display the first VL from network.get_voltage_levels()
+- depth: the diagram depth around the voltage level, controls the size of the sub network. In the SLD tab will be always displayed one diagram, from the VL list currently selected item.
+- low_nominal_voltage_bound: low bound to filter voltage level according to nominal voltage
+- high_nominal_voltage_bound: high bound to filter voltage level according to nominal voltage
+- nad_parameters: layout properties to adjust the svg rendering for the NAD
+- sld_parameters: layout properties to adjust the svg rendering for the SLD

docs/user_guide/sld_widget.md

@@ -0,0 +1,80 @@
+# SLD widget
+
+SLD is an interactive widget that displays a Single Line Diagram SVG, generated for example using the PyPowSyBl APIs, in a Jupyter notebook
+The widget allows you to pan and zoom the diagram, to focus on a specific part when the network is large.
+
+The following code, to be run in a notebook, first creates a network, then displays the SLD widget on it.
+
+```python
+import pypowsybl.network as pn
+from pypowsybl_jupyter import display_sld
+
+network = pn.create_ieee14()
+vl=network.get_voltage_levels().index[1]
+
+sld=display_sld(network.get_single_line_diagram(vl))
+display(sld)
+```
+
+![SLD widget](/_static/img/sld_1.png)
+
+## Update the widget
+
+It is possible to update the widget's content through the update_sld API.
+The code below updates the sld widget already displayed, with a new VL.
+
+```python
+from pypowsybl_jupyter import update_sld
+
+vl1=network.get_voltage_levels().index[5]
+
+update_sld(sld, network.get_single_line_diagram(vl1))
+
+```
+
+## Widget API
+
+```python
+display_sld(svg, enable_callbacks: bool = False, invalid_lf: bool = False) -> SldWidget:
+```
+
+- svg: the input SVG, as str or class providing an svg and metadata representation
+- enable_callbacks: if true, enable the callbacks for navigation arrows, feeders and switches
+- invalid_lf: When True the opacity style for some of the displayed info's (e.g., active and reactive power) is decreased, making them barely visible in the diagram.
+
+
+```python
+update_sld(sldwidget, svg, keep_viewbox: bool = False, enable_callbacks: bool = False, invalid_lf: bool = False)
+```
+
+- sldwidget: the existing widget to update
+- svg: the input NAD's SVG
+- keep_viewbox: if True, keeps the current pan and zoom after the update
+- enable_callbacks: if true, enable the callbacks for navigation arrows, feeders and switches
+- invalid_lf: When True the opacity style for some of the displayed info's (e.g., active and reactive power) is decreased, making them barely visible in the diagram.
+
+
+## Customize widget's interactions
+By default, only the pan and zoom interactions with the diagram are active.
+
+It is possible to customize the widget's behaviour when some of the displayed elements are clicked (e.g., a switch or a VL's arrow) to create more complex interactions (e.g., by integrating other widgets). 
+
+Use these widget's methods to register a callback on a specific event:
+
+- on_nextvl
+- on_switch
+- on_feeder
+- on_bus
+
+The [network explorer](/user_guide/network_explorer.md) demonstrate the approach.
+
+Example: the code below activate a callback when a VL arrow is clicked in the widget. Each time an arrow is clicked, the next VL's id is printed in the log.
+
+```python
+def vl_callback_demo(event):
+        print('Clicked a VL arrow, next VL is: ' + event.clicked_nextvl)
+
+sld_widget=display_sld(network.get_single_line_diagram(network.get_voltage_levels().index[1]), enable_callbacks=True)
+sld_widget.on_nextvl(vl_callback_demo)
+display(sld_widget)
+```