Add documentation.

Add documentation that covers:

- Prediction
- Measuremnt
- REST API

Add Python scripts that support automatic documentation generation using the Sphinx
sphinxcontrib.eval extension.

Add automatic update/ test for REST API documentation.

Filter proxy endpoints from REST API documentation.

Signed-off-by: Bobby Noelte <[email protected]>

.gitignore

@@ -1,8 +1,6 @@
 cache/
 output/
 EOS.config.json
-docs/develop/CONTRIBUTING.md
-docs/develop/getting_started.md
 
 # Default ignore folders and files for VS Code, Python
 
@@ -258,5 +256,5 @@ visualize_output_*.pdf
 *_pdf.png
 
 # Test files
-openapi-new.json
 tests/testdata/new_optimize_result*
+tests/testdata/openapi-new.md

Makefile

@@ -17,6 +17,7 @@ help:
 	@echo "  docker-build - Rebuild docker image"
 	@echo "  docs         - Generate HTML documentation (in build/docs/html/)."
 	@echo "  read-docs    - Read HTML documentation in your browser."
+	@echo "  clean-docs   - Remove generated documentation.""
 	@echo "  run          - Run FastAPI production server in the virtual environment."
 	@echo "  run-dev      - Run FastAPI development server in the virtual environment (automatically reloads)."
 	@echo "  dist         - Create distribution (in dist/)."
@@ -52,13 +53,6 @@ dist: pip
 
 # Target to generate HTML documentation
 docs: pip-dev
-	mkdir -p docs/develop
-	cp README.md docs/develop/getting_started.md
-	# remove top level header and coresponding description
-	sed -i '/^##[^#]/,$$!d' docs/develop/getting_started.md
-	sed -i "1i\# Getting Started\n" docs/develop/getting_started.md
-	cp CONTRIBUTING.md docs/develop
-	sed -i "s/README.md/getting_started.md/g" docs/develop/CONTRIBUTING.md
 	.venv/bin/sphinx-build -M html docs build/docs
 	@echo "Documentation generated to build/docs/html/."
 
@@ -67,12 +61,17 @@ read-docs: docs
 	@echo "Read the documentation in your browser"
 	.venv/bin/python -m webbrowser build/docs/html/index.html
 
-# Clean target to remove generated documentation, distribution and virtual environment
-clean:
-	@echo "Cleaning virtual env, distribution and build directories"
-	rm -rf dist build .venv
+# Clean target to remove generated documentation and documentation artefacts
+clean-docs:
 	@echo "Searching and deleting all '_autosum' directories in docs..."
 	@find docs -type d -name '_autosummary' -exec rm -rf {} +;
+	@echo "Cleaning docs build directories"
+	rm -rf build/docs
+
+# Clean target to remove generated documentation, distribution and virtual environment
+clean: clean-docs
+	@echo "Cleaning virtual env, distribution and build directories"
+	rm -rf build .venv
 	@echo "Deletion complete."
 
 run:

docs/akkudoktoreos/measurement.md

@@ -0,0 +1,93 @@
+% SPDX-License-Identifier: Apache-2.0
+
+# Measurements
+
+Measurements are utilized to refine predictions using real data from your system, thereby enhancing
+accuracy.
+
+- **Household Load Measurement**
+- **Grid Export Measurement**
+- **Grid Import Measurement**
+
+## Storing Measurements
+
+EOS stores measurements in a **key-value store**, where the term `measurement key` refers to the
+unique identifier used to store and retrieve specific measurement data. Note that the key-value
+store is memory-based, meaning that all stored data will be lost upon restarting the EOS REST
+server.
+
+:::{admonition} Todo
+:class: note
+Ensure that measurement data persists across server restarts.
+:::
+
+Several endpoints of the EOS REST server allow for the management and retrieval of these
+measurements.
+
+The measurement data must be or is provided in one of the following formats:
+
+### 1. DateTimeData
+
+A dictionary with the following structure:
+
+```JSON
+    {
+        "start_datetime": "2024-01-01 00:00:00",
+        "interval": "1 Hour",
+        "<measurement key>": [value, value, ...],
+        "<measurement key>": [value, value, ...],
+        ...
+    }
+```
+
+### 2. DateTimeDataFrame
+
+A JSON string created from a [pandas](https://pandas.pydata.org/docs/index.html) dataframe with a
+`DatetimeIndex`. Use [pandas.DataFrame.to_json(orient="index")](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_json.html#pandas.DataFrame.to_json).
+The column name of the data must be the same as the names of the `measurement key`s.
+
+### 3. DateTimeSeries
+
+A JSON string created from a [pandas](https://pandas.pydata.org/docs/index.html) series with a
+`DatetimeIndex`. Use [pandas.Series.to_json(orient="index")](https://pandas.pydata.org/docs/reference/api/pandas.Series.to_json.html#pandas.Series.to_json).
+
+## Load Measurement
+
+The EOS measurement store provides for storing meter readings of loads. There are currently five loads
+foreseen. The associated `measurement key`s are:
+
+- `measurement_load0_mr`: Load0 meter reading [kWh]
+- `measurement_load1_mr`: Load1 meter reading [kWh]
+- `measurement_load2_mr`: Load2 meter reading [kWh]
+- `measurement_load3_mr`: Load3 meter reading [kWh]
+- `measurement_load4_mr`: Load4 meter reading [kWh]
+
+For ease of use, you can assign descriptive names to the `measurement key`s to represent your
+system's load sources. Use the following `configuration options` to set these names
+(e.g., 'Dish Washer', 'Heat Pump'):
+
+- `measurement_load0_name`: Name of the load0 source
+- `measurement_load1_name`: Name of the load1 source
+- `measurement_load2_name`: Name of the load2 source
+- `measurement_load3_name`: Name of the load3 source
+- `measurement_load4_name`: Name of the load4 source
+
+Load measurements can be stored for any datetime. The values between different meter readings are
+linearly approximated. Since optimization occurs on the hour, storing values between hours is
+generally not useful.
+
+The EOS measurement store automatically sums all given loads to create a total load value series
+for specified intervals, usually one hour. This aggregated data can be used for load predictions.
+
+## Grid Export/ Import Measurement
+
+The EOS measurement store also allows for the storage of meter readings for grid import and export.
+The associated `measurement key`s are:
+
+- `measurement_grid_export_mr`: Export to grid meter reading [kWh]
+- `measurement_grid_import_mr`: Import from grid meter reading [kWh]
+
+:::{admonition} Todo
+:class: note
+Currently not used. Integrate grid meter readings into the respective predictions.
+:::