updated docs

ESDLMapEditorESSIM · Jan 18, 2021 · 14f2f65 · 14f2f65
1 parent b559400
commit 14f2f65
Show file tree

Hide file tree

Showing 17 changed files with 196 additions and 95 deletions.
diff --git a/README.md b/README.md
@@ -2,6 +2,24 @@
 
 Project for creating the ReadTheDocs pages for the ESDL MapEditor Documentation
 
-The 'docs' directory contains the documentation information
+The ```docs``` directory contains the documentation information
+
+## Online documentation
+
+This documentation is hosted at: https://esdl-mapeditor-documentation.readthedocs.io/
 
 ## Get up to speed
+
+To generate the documentation:
+
+``` shell
+cd docs
+make html
+```
+
+Then the html is generated in the directory ```docs\build\html```. Open the ```index.html``` in that directory in
+your browser to see your changes.
+
+When you push the changes to the github repository, the online documentation
+is automatically generated within a few minutes.
+
diff --git a/docs/source/basic_tasks/adding_assets.rst b/docs/source/basic_tasks/adding_assets.rst
@@ -0,0 +1,2 @@
+Adding assets
+=============
diff --git a/docs/source/basic_tasks/assigning_profiles.rst b/docs/source/basic_tasks/assigning_profiles.rst
@@ -0,0 +1,3 @@
+Assigning profiles
+==================
+
diff --git a/docs/source/basic_tasks/connecting_assets.rst b/docs/source/basic_tasks/connecting_assets.rst
@@ -0,0 +1,38 @@
+Connecting assets
+=================
+
+ESDL knows the concept of ports and connections to connect assets. Ports exist in two types (by design, see LINK for
+more detailed information):
+
+* InPort: port that is mainly used for incoming flow, current or energy
+* OutPort: port that is mainly used for outgoing flow, current or energy
+
+An InPort is visualized as a blue square to the left on an asset, an OutPort is visualized as a red square to the
+right of an assets. InPorts can only be connected to OutPorts and the other way around.
+
+The amount and type of ports the MapEditor attaches to an asset when the user adds an asset to the map, depends on the
+view mode. The standard behaviour is as follows (for drawing 'single-line systems'):
+
+* Producer: 1 OutPort
+* Consumer: 1 InPort
+* Storage: 1 InPort
+* Conversion: 1 InPort and 1 OutPort
+
+  * There are two exceptions to this rule, for the CoGeneration types (CHP and FuelCell): They'll get 1 InPort and 2 OutPorts
+
+* Transport: 1 InPort and 1 OutPort
+
+.. image:: images/assets_with_ports.png
+  :width: 800
+  :alt: Different asset types with the standard amount of Ports
+
+If you switch the view mode to 'CHESS', this behaviour changes to (for drawing 'double-line systems'):
+
+* Producer: 1 InPort and 1 OutPort
+* Consumer: 1 InPort and 1 OutPort
+* Storage: 1 InPort and 1 OutPort
+* Conversion: *** To be discussed ***
+* Transport: 1 InPort and 1 OutPort
+
+  * There are two exceptions to this rule, for the Transformer and HeatExchange: They'll get 1 InPort and 1 OutPort
+    for the primary side and 1 InPort and 1 OutPort for the secondary side
diff --git a/docs/source/basic_tasks/creating_an_energy_system_description.rst b/docs/source/basic_tasks/creating_an_energy_system_description.rst
@@ -0,0 +1,2 @@
+Creating an energy system description
+=====================================
diff --git a/docs/source/basic_tasks/defining_and_setting_energy_carriers.rst b/docs/source/basic_tasks/defining_and_setting_energy_carriers.rst
@@ -0,0 +1,3 @@
+Defining and setting energy carriers
+====================================
+
diff --git a/docs/source/basic_tasks/images/assets_with_ports.png b/docs/source/basic_tasks/images/assets_with_ports.png
diff --git a/docs/source/basic_tasks/index.rst b/docs/source/basic_tasks/index.rst
@@ -0,0 +1,14 @@
+Basic tasks in the ESDL MapEditor
+=================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Subsections:
+
+   creating_an_energy_system_description
+   adding_assets
+   removing_assets
+   connecting_assets
+   removing_a_connection
+   defining_and_setting_energy_carriers
+   assigning_profiles
diff --git a/docs/source/basic_tasks/removing_a_connection.rst b/docs/source/basic_tasks/removing_a_connection.rst
@@ -0,0 +1,3 @@
+Removing a connection
+=====================
+
diff --git a/docs/source/basic_tasks/removing_assets.rst b/docs/source/basic_tasks/removing_assets.rst
@@ -0,0 +1,2 @@
+Removing assets
+===============
diff --git a/docs/source/features/asset_draw_toolbar.rst b/docs/source/features/asset_draw_toolbar.rst
@@ -0,0 +1,3 @@
+Asset Draw Toolbar
+==================
+
diff --git a/docs/source/features/index.rst b/docs/source/features/index.rst
@@ -5,6 +5,7 @@ ESDL MapEditor features
    :maxdepth: 2
    :caption: Contents:
 
+   asset_draw_toolbar
    boundary_service
    building_information
    building_editor

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -8,6 +8,7 @@ Welcome to the ESDL MapEditor documentation
    introduction/index
    user_interface/index
    esdl/index
+   basic_tasks/index
    features/index
    external_services/index
    examples/index

diff --git a/docs/source/introduction/index.rst b/docs/source/introduction/index.rst
@@ -1,6 +1,11 @@
 Introduction
 ============
 
+.. note::
+    This documentation is work in progress and far from finished. New sections will be added in the near future.
+    Whenever questions or feedback is received from end users, we're trying to update this documentation on the fly.
+    So don't hesitate to contact us, whenever you run into problems.
+
 The ESDL MapEditor is a map based editor for energy systems or energy transition scenarios. It is fully based on the
 Energy System Description Language (ESDL).
 

diff --git a/docs/source/user_interface/index.rst b/docs/source/user_interface/index.rst
@@ -30,98 +30,9 @@ Number Description
 16     Shows the coordinates (lat/lon) of the mouse pointer on the map
 ====== ====================================================================
 
-Top level menus (1)
--------------------
+.. toctree::
+   :maxdepth: 2
+   :caption: Subsections:
 
-File menu
-^^^^^^^^^
-
-.. csv-table::
-    :header: "Menu item", "Description"
-
-    "New ESDL", "Start with a new empty energy system. Remove all current ESDL files loaded."
-    "Load ESDL", "Load an ESDL file from your local file system. Remove all current ESDL files loaded."
-    "Import ESDL", "Import an ESDL file from your local file system. This ESDL will be added to the list of loaded ESDLs in the layer control section (7)."
-    "Save ESDL", "Save the currently selected ESDL to your local file system."
-    "Load from ESDL drive", "Load or import an ESDL file from the ESDL drive (ESDL cloud storage)."
-    "Save to ESDL drive", "Save an ESDL to the ESDL drive."
-
-Only for Mondaine project partners (the Mondaine Hub was the predecessor of the ESDL drive):
-
-.. csv-table::
-    :header: "Menu item", "Description"
-
-    "Load ESDL from Mondaine Hub", "Load or import an ESDL file from the Mondaine Hub"
-    "Save ESDL to Mondaine Hub", "Save an ESDL file to the Mondaine Hub"
-
-.. note::
-    When you press 'Save ESDL' in the ESDL MapEditor, the behaviour is determined by your local browser settings. Most
-    browsers by default save files in the Downloads folder (on Windows at least). In your browser settings you can
-    specify to ask the user for a file location
-
-Edit menu
-^^^^^^^^^
-
-.. csv-table::
-    :header: "Menu item", "Description"
-
-    "ESDL browser", ""
-    "Energy carriers", ""
-    "Sectors", ""
-    "Shapefile converter", ""
-
-Services menu
-^^^^^^^^^^^^^
-
-.. csv-table::
-    :header: "Menu item", "Description"
-
-    "Energy system statistics", ""
-    "External ESDL services", ""
-    "Get boundary information", ""
-    "ESSIM simulation", ""
-    "Load animation", ""
-    "ESDL compare", ""
-    "ESDL merge", ""
-
-View menu
-^^^^^^^^^
-
-.. csv-table::
-    :header: "Menu item", "Description"
-
-    "WMS layers", "Allows to visualize WMS layers in the MapEditor"
-    "Show/hide animation toolbar", "Show or hide the animation toolbar - for controlling the load animation"
-    "Show/hide asset draw toolbar", "Show or hide the asset draw toolbar - for quickly adding certain assets"
-    "Show/hide KPIs", "Show or hide KPI window"
-    "Settings", "Settings for the MapEditor and its plugins"
-
-Layer control (7)
------------------
-
-The layer control is split into two sections:
-* Base layers
-* ESDL layers
-
-The base layers section allows you to choose the backgorund of the map, either openstreetmap (the default), google or
-no map. The latter one can be used for schematic diagrams where the physical location is not important.
-
-In the ESDL layer section you will find one item for each ESDL loaded in the MapEditor. The ESDL information is separated
-in different layers that can each be shown or hidden. See the table below for a detailed description of the different
-ESDL sub layers.
-
-.. image:: images/layer_control.png
-  :alt: ESDL layer control
-
-================== =========================================================
-Layer              Description
-================== =========================================================
-Area               Layer showing the area boundaries
-Assets             Layer showing all ESDL assets
-Connections        Layer showing logical connections between assets
-Buildings          Layer showing building geometries
-Potentials         Layer showing energy potential information
-KPIs               Layer showing KPIs
-Simulation results Layer showing simulation results, like animation of loads
-Notes              Layer showing the notes
-================== =========================================================
+   menus
+   layer_control
diff --git a/docs/source/user_interface/layer_control.rst b/docs/source/user_interface/layer_control.rst
@@ -0,0 +1,30 @@
+Layer control
+=============
+
+The layer control is split into two sections:
+
+* Base layers
+* ESDL layers
+
+The base layers section allows you to choose the backgorund of the map, either openstreetmap (the default), google or
+no map. The latter one can be used for schematic diagrams where the physical location is not important.
+
+In the ESDL layer section you will find one item for each ESDL loaded in the MapEditor. The ESDL information is separated
+in different layers that can each be shown or hidden. See the table below for a detailed description of the different
+ESDL sub layers.
+
+.. image:: images/layer_control.png
+  :alt: ESDL layer control
+
+================== =========================================================
+Layer              Description
+================== =========================================================
+Area               Layer showing the area boundaries
+Assets             Layer showing all ESDL assets
+Connections        Layer showing logical connections between assets
+Buildings          Layer showing building geometries
+Potentials         Layer showing energy potential information
+KPIs               Layer showing KPIs
+Simulation results Layer showing simulation results, like animation of loads
+Notes              Layer showing the notes
+================== =========================================================
diff --git a/docs/source/user_interface/menus.rst b/docs/source/user_interface/menus.rst
@@ -0,0 +1,65 @@
+Top level menus
+---------------
+
+File menu
+^^^^^^^^^
+
+.. csv-table::
+    :header: "Menu item", "Description"
+
+    "New ESDL", "Start with a new empty energy system. Remove all current ESDL files loaded."
+    "Load ESDL", "Load an ESDL file from your local file system. Remove all current ESDL files loaded."
+    "Import ESDL", "Import an ESDL file from your local file system. This ESDL will be added to the list of loaded ESDLs in the layer control section (7)."
+    "Save ESDL", "Save the currently selected ESDL to your local file system."
+    "Load from ESDL drive", "Load or import an ESDL file from the ESDL drive (ESDL cloud storage)."
+    "Save to ESDL drive", "Save an ESDL to the ESDL drive."
+
+Only for Mondaine project partners (the Mondaine Hub was the predecessor of the ESDL drive):
+
+.. csv-table::
+    :header: "Menu item", "Description"
+
+    "Load ESDL from Mondaine Hub", "Load or import an ESDL file from the Mondaine Hub"
+    "Save ESDL to Mondaine Hub", "Save an ESDL file to the Mondaine Hub"
+
+.. note::
+    When you press 'Save ESDL' in the ESDL MapEditor, the behaviour is determined by your local browser settings. Most
+    browsers by default save files in the Downloads folder (on Windows at least). In your browser settings you can
+    specify to ask the user for a file location
+
+Edit menu
+^^^^^^^^^
+
+.. csv-table::
+    :header: "Menu item", "Description"
+
+    "ESDL browser", ""
+    "Energy carriers", ""
+    "Sectors", ""
+    "Shapefile converter", ""
+
+Services menu
+^^^^^^^^^^^^^
+
+.. csv-table::
+    :header: "Menu item", "Description"
+
+    "Energy system statistics", ""
+    "External ESDL services", ""
+    "Get boundary information", ""
+    "ESSIM simulation", ""
+    "Load animation", ""
+    "ESDL compare", ""
+    "ESDL merge", ""
+
+View menu
+^^^^^^^^^
+
+.. csv-table::
+    :header: "Menu item", "Description"
+
+    "WMS layers", "Allows to visualize WMS layers in the MapEditor"
+    "Show/hide animation toolbar", "Show or hide the animation toolbar - for controlling the load animation"
+    "Show/hide asset draw toolbar", "Show or hide the asset draw toolbar - for quickly adding certain assets"
+    "Show/hide KPIs", "Show or hide KPI window"
+    "Settings", "Settings for the MapEditor and its plugins"