improving doc

BDonnot · Sep 3, 2024 · bc61ead · bc61ead
1 parent caf5e30
commit bc61ead
Show file tree

Hide file tree

Showing 24 changed files with 523 additions and 144 deletions.
diff --git a/docs/data_pipeline.rst b/docs/data_pipeline.rst
@@ -55,9 +55,9 @@ Results are reported in the table below:
 ==============================  ================  ===================
 Method used                     memory footprint  time to perform (s)
 ==============================  ================  ===================
-Nothing (see `Basic Usage`_)    low                44.6
-set_chunk (see `Chunk size`_)   ultra low          26.8
-`MultifolderWithCache`_         high               11.0
+Nothing (see Basic Usage )       low                44.6
+set_chunk (see `Chunk size`_ )   ultra low          26.8
+`MultifolderWithCache`_          high               11.0
 ==============================  ================  ===================
 
 As you can see, the default usage uses relatively little memory but takes a while to compute (almost 45s to perform

diff --git a/docs/developer/create_an_environment.rst b/docs/developer/create_an_environment.rst
@@ -1,8 +1,8 @@
-.. |l2rpn_case14_sandbox_layout| image:: ./img/l2rpn_case14_sandbox_layout.png
-.. |R2_full_grid| image:: ./img/R2_full_grid.png
-.. |l2rpn_neurips_2020_track1_layout| image:: ./img/l2rpn_neurips_2020_track1_layout.png
-.. |l2rpn_neurips_2020_track2_layout| image:: ./img/l2rpn_neurips_2020_track2_layout.png
-.. |l2rpn_wcci_2022_layout| image:: ./img/l2rpn_wcci_2022_layout.png
+.. |l2rpn_case14_sandbox_layout| image:: ../img/l2rpn_case14_sandbox_layout.png
+.. |R2_full_grid| image:: ../img/R2_full_grid.png
+.. |l2rpn_neurips_2020_track1_layout| image:: ../img/l2rpn_neurips_2020_track1_layout.png
+.. |l2rpn_neurips_2020_track2_layout| image:: ../img/l2rpn_neurips_2020_track2_layout.png
+.. |l2rpn_wcci_2022_layout| image:: ../img/l2rpn_wcci_2022_layout.png
 
 
 Possible workflow to create an environment from existing time series

diff --git a/docs/developer/createbackend.rst b/docs/developer/createbackend.rst
@@ -21,26 +21,26 @@
 .. _line_or_pos_topo_vect: ./space.html#grid2op.Space.GridObjects.line_or_pos_topo_vect
 .. _line_ex_pos_topo_vect: ./space.html#grid2op.Space.GridObjects.line_ex_pos_topo_vect
 
-.. |5subs_grid_layout| image:: ./img/5subs_grid_layout.jpg
-.. |5subs_grid_1_sub| image:: ./img/5subs_grid_1_sub.jpg
-.. |5subs_grid_2_loads| image:: ./img/5subs_grid_2_loads.jpg
-.. |5subs_grid_3_gens| image:: ./img/5subs_grid_3_gens.jpg
-.. |5subs_grid_4_lines| image:: ./img/5subs_grid_4_lines.jpg
-.. |5subs_grid_5_obj_in_sub| image:: ./img/5subs_grid_5_obj_in_sub.jpg
-.. |5subs_grid_layout_with_repr| image:: ./img/5subs_grid_layout_with_repr.jpg
-.. |5subs_grid_n_el| image:: ./img/5subs_grid_n_el.jpg
-.. |5subs_grid_5_sub_i| image:: ./img/5subs_grid_5_sub_i.jpg
-.. |5subs_grid_load_to_subid| image:: ./img/5subs_grid_load_to_subid.jpg
-.. |5subs_grid_el_to_subid| image:: ./img/5subs_grid_el_to_subid.jpg
-.. |5subs_grid_sub0| image:: ./img/5subs_grid_sub0.jpg
-.. |5subs_grid_sub0_final| image:: ./img/5subs_grid_sub0_final.jpg
-.. |5subs_grid_sub1_final| image:: ./img/5subs_grid_sub1_final.jpg
-.. |5subs_grid_loads_info| image:: ./img/5subs_grid_loads_info.jpg
-.. |5subs_grid_sub1_topo| image:: ./img/5subs_grid_sub1_topo.jpg
-.. |5subs_grid_sub1_2_topo| image:: ./img/5subs_grid_sub1_2_topo.jpg
-.. |5subs_grid_suball_topo| image:: ./img/5subs_grid_suball_topo.jpg
-.. |5subs_grid_ex_disco| image:: ./img/5subs_grid_ex_disco.jpg
-.. |5subs_grid_ex_2buses| image:: ./img/5subs_grid_ex_2buses.jpg
+.. |5subs_grid_layout| image:: ../img/5subs_grid_layout.jpg
+.. |5subs_grid_1_sub| image:: ../img/5subs_grid_1_sub.jpg
+.. |5subs_grid_2_loads| image:: ../img/5subs_grid_2_loads.jpg
+.. |5subs_grid_3_gens| image:: ../img/5subs_grid_3_gens.jpg
+.. |5subs_grid_4_lines| image:: ../img/5subs_grid_4_lines.jpg
+.. |5subs_grid_5_obj_in_sub| image:: ../img/5subs_grid_5_obj_in_sub.jpg
+.. |5subs_grid_layout_with_repr| image:: ../img/5subs_grid_layout_with_repr.jpg
+.. |5subs_grid_n_el| image:: ../img/5subs_grid_n_el.jpg
+.. |5subs_grid_5_sub_i| image:: ../img/5subs_grid_5_sub_i.jpg
+.. |5subs_grid_load_to_subid| image:: ../img/5subs_grid_load_to_subid.jpg
+.. |5subs_grid_el_to_subid| image:: ../img/5subs_grid_el_to_subid.jpg
+.. |5subs_grid_sub0| image:: ../img/5subs_grid_sub0.jpg
+.. |5subs_grid_sub0_final| image:: ../img/5subs_grid_sub0_final.jpg
+.. |5subs_grid_sub1_final| image:: ../img/5subs_grid_sub1_final.jpg
+.. |5subs_grid_loads_info| image:: ../img/5subs_grid_loads_info.jpg
+.. |5subs_grid_sub1_topo| image:: ../img/5subs_grid_sub1_topo.jpg
+.. |5subs_grid_sub1_2_topo| image:: ../img/5subs_grid_sub1_2_topo.jpg
+.. |5subs_grid_suball_topo| image:: ../img/5subs_grid_suball_topo.jpg
+.. |5subs_grid_ex_disco| image:: ../img/5subs_grid_ex_disco.jpg
+.. |5subs_grid_ex_2buses| image:: ../img/5subs_grid_ex_2buses.jpg
 
 .. _create-backend-module:
 
@@ -689,15 +689,16 @@ These functions can be used in the following manner:
 
 And of course you do the same for generators and both ends of each powerline.
 
-.. note:: About powerline, grid2op adopts the following convention: a powerline **cannot** be connected on one side
+.. note:: 
+    About powerline, grid2op adopts the following convention: a powerline **cannot** be connected on one side
     and disconnected on the other.
 
     That being said, it's still possible to connect the extremity of a powerline "alone" on a busbar, which will have
     the same effect of having it "disconnected at one ends only".
 
 .. _vector-orders-create-backend:
 
-***_infos() : Read back the results (flows, voltages etc.)
+\*\*\*_infos() : Read back the results (flows, voltages etc.)
 --------------------------------------------------------------
 This last "technical" part concerns what can be refer to as "getters" from the backend. These functions allow to
 read back the state of the grid and expose its results to grid2op in a standardize manner.

diff --git a/docs/developer/env_content.rst b/docs/developer/env_content.rst
@@ -1,9 +1,9 @@
 
-.. |l2rpn_case14_sandbox_layout| image:: ./img/l2rpn_case14_sandbox_layout.png
-.. |R2_full_grid| image:: ./img/R2_full_grid.png
-.. |l2rpn_neurips_2020_track1_layout| image:: ./img/l2rpn_neurips_2020_track1_layout.png
-.. |l2rpn_neurips_2020_track2_layout| image:: ./img/l2rpn_neurips_2020_track2_layout.png
-.. |l2rpn_wcci_2022_layout| image:: ./img/l2rpn_wcci_2022_layout.png
+.. |l2rpn_case14_sandbox_layout| image:: ../img/l2rpn_case14_sandbox_layout.png
+.. |R2_full_grid| image:: ../img/R2_full_grid.png
+.. |l2rpn_neurips_2020_track1_layout| image:: ../img/l2rpn_neurips_2020_track1_layout.png
+.. |l2rpn_neurips_2020_track2_layout| image:: ../img/l2rpn_neurips_2020_track2_layout.png
+.. |l2rpn_wcci_2022_layout| image:: ../img/l2rpn_wcci_2022_layout.png
 
 
 Content of an environment

diff --git a/docs/grid2op_dev.rst b/docs/grid2op_dev.rst
@@ -0,0 +1,7 @@
+.. toctree::
+    :maxdepth: 1
+
+    grid2op_dev/action
+    grid2op_dev/observation
+
+.. include:: final.rst
diff --git a/docs/grid2op_dev/action.rst b/docs/grid2op_dev/action.rst
@@ -0,0 +1,7 @@
+How to add a new type of action
+===================================
+
+Work in progress !
+
+
+.. include:: final.rst
diff --git a/docs/grid2op_dev/observation.rst b/docs/grid2op_dev/observation.rst
@@ -0,0 +1,7 @@
+How to add a new attribute to the observation
+==============================================
+
+Work in progress !
+
+
+.. include:: final.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -162,14 +162,16 @@ deeply into the other section of the documentation.
 
    user
 
-External contribution technical Documentation
-------------------------------------------------
+
+Technical documentation for grid2op "external" contributions
+----------------------------------------------------------------
 
 This part of the documentation is focued on external contribution.
 It is best suited if you want to use grid2op as a "core" and extend / modify
 it with different elements.
 
 For example, you might want to :
+
 - use a different solver to compute powerflows 
   (called :class:`grid2op.Backend.Backend` in grid2op)
 - create a new environment
@@ -185,18 +187,47 @@ are done internally whenever possible.
 
 This is the type of documentation you should be looking at if the 
 current grid2op modelling statisfies you in its vast majority 
-but if you want to slightly modify one of its component
+but if you want to slightly modify one of its component.
+
+.. note::
+   This type of contribution can be developed and hosted in a different 
+   github repository than grid2op (*eg* lightsim2grid, another faster backend
+   is hosted on https://github.com/bdonnot/lightsim2grid.git)
+
+   Feel free to contact us if you have done such an "external contribution" so 
+   that we can at least reference it in the documentation.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Technical documentation for grid2op external contributors
+   :caption: Technical documentation for grid2op "external" contributions
 
    developer
 
-Developer technical Documentation
------------------------------------
 
+Technical documentation for grid2op developers
+-------------------------------------------------
+
+This part of the documentation also focuses on external contribution. It
+focuses on the core of grid2op. If you want to :
+
+- change the grid2op internal representation
+- add a functionality to grid2op (*eg* a new type of actions or a new attribute to the observation)
+- change the representatino of this or this elements
+- etc.
+
+We encourage you to get in touch with us for such development. 
+
+.. note::
+   Most of the work falling into this category should probably be 
+   integrated into the main grid2op repository.
+
+.. warning:: 
+   DOC IN PROGRESS...
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Technical documentation for grid2op developers
 
-DOC IN PROGRESS...
+   grid2op_dev
 
 .. include:: final.rst
diff --git a/docs/mdp.rst b/docs/mdp.rst
@@ -1,5 +1,9 @@
-.. include:: special.rst
+.. for the color
+.. include:: special.rst 
 
+.. for the observation attributes
+.. include:: user/special.rst
+
 .. _mdp-doc-module:
 
 Dive into grid2op sequential decision process

diff --git a/docs/special.rst b/docs/special.rst
@@ -38,71 +38,4 @@
 .. role:: center
 .. role:: left
 .. role:: right
-.. (c) Lilian Besson, 2011-2016, https://bitbucket.org/lbesson/web-sphinx/
-
-.. _n_gen: ./space.html#grid2op.Space.GridObjects.n_gen
-.. _n_load: ./space.html#grid2op.Space.GridObjects.n_load
-.. _n_line: ./space.html#grid2op.Space.GridObjects.n_line
-.. _n_sub: ./space.html#grid2op.Space.GridObjects.n_sub
-.. _n_storage: ./space.html#grid2op.Space.GridObjects.n_storage
-.. _dim_topo: ./space.html#grid2op.Space.GridObjects.dim_topo
-.. _dim_alarms: ./space.html#grid2op.Space.GridObjects.dim_alarms
-.. _dim_alerts: ./space.html#grid2op.Space.GridObjects.dim_alerts
-.. _year: ./observation.html#grid2op.Observation.BaseObservation.year
-.. _month: ./observation.html#grid2op.Observation.BaseObservation.month
-.. _day: ./observation.html#grid2op.Observation.BaseObservation.day
-.. _hour_of_day: ./observation.html#grid2op.Observation.BaseObservation.hour_of_day
-.. _minute_of_hour: ./observation.html#grid2op.Observation.BaseObservation.minute_of_hour
-.. _day_of_week: ./observation.html#grid2op.Observation.BaseObservation.day_of_week
-.. _gen_p: ./observation.html#grid2op.Observation.BaseObservation.gen_p
-.. _gen_q: ./observation.html#grid2op.Observation.BaseObservation.gen_q
-.. _gen_v: ./observation.html#grid2op.Observation.BaseObservation.gen_v
-.. _load_p: ./observation.html#grid2op.Observation.BaseObservation.load_p
-.. _load_q: ./observation.html#grid2op.Observation.BaseObservation.load_q
-.. _load_v: ./observation.html#grid2op.Observation.BaseObservation.load_v
-.. _p_or: ./observation.html#grid2op.Observation.BaseObservation.p_or
-.. _q_or: ./observation.html#grid2op.Observation.BaseObservation.q_or
-.. _v_or: ./observation.html#grid2op.Observation.BaseObservation.v_or
-.. _a_or: ./observation.html#grid2op.Observation.BaseObservation.a_or
-.. _p_ex: ./observation.html#grid2op.Observation.BaseObservation.p_ex
-.. _q_ex: ./observation.html#grid2op.Observation.BaseObservation.q_ex
-.. _v_ex: ./observation.html#grid2op.Observation.BaseObservation.v_ex
-.. _a_ex: ./observation.html#grid2op.Observation.BaseObservation.a_ex
-.. _rho: ./observation.html#grid2op.Observation.BaseObservation.rho
-.. _topo_vect: ./observation.html#grid2op.Observation.BaseObservation.topo_vect
-.. _line_status: ./observation.html#grid2op.Observation.BaseObservation.line_status
-.. _timestep_overflow: ./observation.html#grid2op.Observation.BaseObservation.timestep_overflow
-.. _time_before_cooldown_line: ./observation.html#grid2op.Observation.BaseObservation.time_before_cooldown_line
-.. _time_before_cooldown_sub: ./observation.html#grid2op.Observation.BaseObservation.time_before_cooldown_sub
-.. _time_next_maintenance: ./observation.html#grid2op.Observation.BaseObservation.time_next_maintenance
-.. _duration_next_maintenance: ./observation.html#grid2op.Observation.BaseObservation.duration_next_maintenance
-.. _target_dispatch: ./observation.html#grid2op.Observation.BaseObservation.target_dispatch
-.. _actual_dispatch: ./observation.html#grid2op.Observation.BaseObservation.actual_dispatch
-.. _storage_charge: ./observation.html#grid2op.Observation.BaseObservation.storage_charge
-.. _storage_power_target: ./observation.html#grid2op.Observation.BaseObservation.storage_power_target
-.. _storage_power: ./observation.html#grid2op.Observation.BaseObservation.storage_power
-.. _storage_theta: ./observation.html#grid2op.Observation.BaseObservation.storage_theta
-.. _gen_p_before_curtail: ./observation.html#grid2op.Observation.BaseObservation.gen_p_before_curtail
-.. _curtailment: ./observation.html#grid2op.Observation.BaseObservation.curtailment
-.. _curtailment_limit: ./observation.html#grid2op.Observation.BaseObservation.curtailment_limit
-.. _is_alarm_illegal: ./observation.html#grid2op.Observation.BaseObservation.is_alarm_illegal
-.. _time_since_last_alarm: ./observation.html#grid2op.Observation.BaseObservation.time_since_last_alarm
-.. _last_alarm: ./observation.html#grid2op.Observation.BaseObservation.last_alarm
-.. _attention_budget: ./observation.html#grid2op.Observation.BaseObservation.attention_budget
-.. _max_step: ./observation.html#grid2op.Observation.BaseObservation.max_step
-.. _current_step: ./observation.html#grid2op.Observation.BaseObservation.current_step
-.. _delta_time: ./observation.html#grid2op.Observation.BaseObservation.delta_time
-.. _gen_margin_up: ./observation.html#grid2op.Observation.BaseObservation.gen_margin_up
-.. _gen_margin_down: ./observation.html#grid2op.Observation.BaseObservation.gen_margin_down
-.. _curtailment_mw: ./observation.html#grid2op.Observation.BaseObservation.curtailment_mw
-.. _theta_or: ./observation.html#grid2op.Observation.BaseObservation.theta_or
-.. _theta_ex: ./observation.html#grid2op.Observation.BaseObservation.theta_ex
-.. _gen_theta: ./observation.html#grid2op.Observation.BaseObservation.gen_theta
-.. _load_theta: ./observation.html#grid2op.Observation.BaseObservation.load_theta
-.. _active_alert: ./observation.html#grid2op.Observation.BaseObservation.active_alert
-.. _time_since_last_alert: ./observation.html#grid2op.Observation.BaseObservation.time_since_last_alert
-.. _alert_duration: ./observation.html#grid2op.Observation.BaseObservation.alert_duration
-.. _total_number_of_alert: ./observation.html#grid2op.Observation.BaseObservation.total_number_of_alert
-.. _time_since_last_attack: ./observation.html#grid2op.Observation.BaseObservation.time_since_last_attack
-.. _was_alert_used_after_attack: ./observation.html#grid2op.Observation.BaseObservation.was_alert_used_after_attack
-.. _attack_under_alert: ./observation.html#grid2op.Observation.BaseObservation.attack_under_alert
+.. (c) Lilian Besson, 2011-2016, https://bitbucket.org/lbesson/web-sphinx/