Added documentation for dataset creation

docs/source/endpoints.rst

@@ -1,3 +1,5 @@
+.. _rest_endpoints:
+
 Endpoints of REST-API
 =====================
 

docs/source/index.rst

@@ -8,7 +8,7 @@ Welcome to Python-Starter documentation!
    This project is under active development.
 
 Check out the :doc:`usage` section for further information, including how to
-:ref:`install <installation>` the project.
+install the project.
 
 Indices and tables
 ==================
@@ -22,6 +22,7 @@ Indices and tables
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
+   :hidden:
 
    usage
    endpoints

docs/source/usage.rst

@@ -1,13 +1,28 @@
 Usage
 =====
 
-.. _installation:
 
+
+Kurze Einleitung:
+Daten einlesen bzw. eingelesene nutzen
+Daten sind in unterschiedliche Bereiche aufgeteilt
+
+
+
+Verweis auf:
 Installation
-------------
+Daten einlesen bzw. Aufbau der Daten in Datensatz + Modell
+Modell starten bzw. Optimierung durchführen
+Ergebnisse auslesen
+
 
-See the `installation instructions on Github <https://github.com/NOWUM/EnSysMod#installation>`_.
+.. toctree::
+    :maxdepth: 1
+    :caption: Contents:
+    :glob:
+    :hidden:
 
+    usage/*
 
 
 

docs/source/usage/1_installation.rst

@@ -0,0 +1,8 @@
+Installation
+------------
+
+See the `installation instructions on Github <https://github.com/NOWUM/EnSysMod#installation>`_.
+
+
+
+

docs/source/usage/2_dataset.rst

@@ -0,0 +1,129 @@
+*******
+Dataset
+*******
+
+.. _introduction:
+
+Introduction
+============
+
+
+A dataset has different components. It contains commodities, as which energy source is used in the energy system, and the regions, your energy system is based on.
+Furthermore the dataset consists of energy sources, sinks, storages, conversions and transmissions.
+
+With one dataset several modeling runs can be performed.
+
+.. _newDataset:
+
+Create a new dataset
+====================
+To create a new dataset, the API REST interface ``POST /datasets/`` is addressed. You can provide the following
+parameters:
+
+- `name`: name of the dataset
+
+- `description`: description of the dataset
+
+The endpoint returns the id of the new dataset. That will be needed in the following steps.
+
+A full documentation of the API is available `as redoc documentation <https://http://10.13.10.51:9000/redoc>`_.
+
+.. openapi:: ./../generated/openapi.json
+   :paths:
+      /datasets/
+
+.. _readData:
+
+Read data
+=========
+There are two ways to add data to a dataset. For both ways you need to provide the id of the dataset.
+
+Zip-Upload 
+----------
+With the Zip-Upload, we've created a way to enter the data in the database with only one use of a API REST interface.
+Once a zip archive is created in a certain format and with certain files, it can be uploaded with the API REST interface.
+A dataset id is needed.
+
+.. openapi:: ./../generated/openapi.json
+   :include:
+      /datasets/*/upload
+
+The zip archive contains other files and folder in which the regions, commodities and components to the energy system
+are described. The zip archive is structured as follows:
+
+.. code-block:: bash
+
+   dataset.zip
+    │   commodities.json
+    │   regions.json
+    ├───conversions/
+    ├───sinks/
+    ├───sources/
+    ├───storages/
+    └───transmissions/
+
+The ```commodities.json`` contains all commodities, which are used in the energy system.
+The json file is structured as a list of commodities with name, unit and description.
+The unit is used for all values in the energy system with that specific commodity.
+Example:
+
+.. code-block:: json
+
+   [
+       {
+           "name": "electricity",
+           "unit": "kWh",
+           "description": "example description"
+       },
+       {
+           "name": "heat",
+           "unit": "kWh"
+       }
+  ]
+
+
+The ``regions.json`` contains all regions, which are used in the energy system.
+The json file is structured as a list of regions with name and description. Example:
+
+.. code-block:: json
+
+   [
+       {
+           "name": "region1",
+           "description": "example description"
+       },
+       {
+           "name": "region2"
+       }
+  ]
+
+
+For each of the sections for energy sources, sinks, storages, conversions and transmissions exists a folder.
+These folders contain other folders that are used as a listing of the various objects.
+
+.. code-block:: bash
+
+   dataset.zip
+    └───sources/
+        ├───source-1/
+        │       capacity.xlsx
+        │       operationRateMax.xlsx
+        │       source.json
+        └───source-2/
+                capacity.xlsx
+                operationRateFix.xlsx
+                source.json
+
+For example, there are two folders in the source folder that contains data for two different energy sources.
+A folder that maps an object contains a .json file that contains the parameters for the object, which are the same
+across all regions. If there are parameters that are different for each region, these parameters (for example
+capacity per region, operation rates, ...) are stored in one Excel file each.
+Each region is mapped as a column and the value (or values as a time series) is stored in the column according to the region.
+
+The parameter that are needed for each object are documented here (TODO Link). All of the parameters can be set, but not all of them have to.
+
+To show the structure of the zip file, we have created an example. This can be found `here <https://github.com/NOWUM/EnSysMod/tree/main/examples/data/dataset-1/>`_.
+
+Upload data per REST API interfaces individually
+------------------------------------------------
+Another way is to upload the data in small pieces via the individual REST interfaces. A list of the interfaces can be found :ref:`here. <rest_endpoints>`..

docs/source/usage/3_model.rst

@@ -0,0 +1,5 @@
+******
+Modell
+******
+
+hat Kosten und Reduktionsziele

docs/source/usage/execute.rst

@@ -0,0 +1,5 @@
+*******************
+Optimierung starten
+*******************
+
+Optimierung

docs/source/usage/output.rst

@@ -0,0 +1,5 @@
+******************
+Ergebnisse abrufen
+******************
+
+Output