mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2025-03-18 18:44:04 +00:00
Adapt documentation generation to be compliant to ReadTheDocs and Windows. (#341)
Use documentation generation tools that are available for Windows and Linux. Use python instead of shell scripts to generate documentation. For ReadTheDocs make generated documentation content static to avoid running scripts outside of the docs/ path which is the default path for ReadTheDOcs. Add tests that check if generated content does go out of sync with latest source. Use tabs to show commands for Windows and Linux to improve user experience. Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
This commit is contained in:
Bobby Noelte
GitHub
parent
d4e31d556a
commit
214768795f
1
.gitignore
vendored
1
.gitignore
vendored
@ -259,3 +259,4 @@ visualize_output_*.pdf
|
||||
tests/testdata/new_optimize_result*
|
||||
tests/testdata/openapi-new.json
|
||||
tests/testdata/openapi-new.md
|
||||
tests/testdata/config-new.md
|
||||
|
||||
12
Makefile
12
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 " gen-docs - Generate openapi.json and docs/_generated/*.""
|
||||
@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)."
|
||||
@ -51,10 +52,17 @@ dist: pip
|
||||
.venv/bin/python -m build --wheel
|
||||
@echo "Distribution created (see dist/)."
|
||||
|
||||
# Target to generate HTML documentation
|
||||
# Target to generate documentation
|
||||
gen-docs: pip-dev
|
||||
.venv/bin/python ./scripts/generate_config_md.py --output-file docs/_generated/config.md
|
||||
.venv/bin/python ./scripts/generate_openapi_md.py --output-file docs/_generated/openapi.md
|
||||
.venv/bin/python ./scripts/generate_openapi.py --output-file openapi.json
|
||||
@echo "Documentation generated to openapi.json and docs/_generated."
|
||||
|
||||
# Target to build HTML documentation
|
||||
docs: pip-dev
|
||||
.venv/bin/sphinx-build -M html docs build/docs
|
||||
@echo "Documentation generated to build/docs/html/."
|
||||
@echo "Documentation build to build/docs/html/."
|
||||
|
||||
# Target to read the HTML documentation
|
||||
read-docs: docs
|
||||
|
||||
309
docs/_generated/config.md
Normal file
309
docs/_generated/config.md
Normal file
@ -0,0 +1,309 @@
|
||||
# Configuration Table
|
||||
|
||||
## General Configuration Values
|
||||
|
||||
:::{table} General Configuration Values
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `config_default_file_path` | `<class 'pathlib.Path'>` | `ro` | `N/A` | Compute the default config file path. |
|
||||
| `config_file_path` | `Optional[pathlib.Path]` | `ro` | `N/A` | Path to EOS configuration file. |
|
||||
| `config_folder_path` | `Optional[pathlib.Path]` | `ro` | `N/A` | Path to EOS configuration directory. |
|
||||
| `config_keys` | `List[str]` | `ro` | `N/A` | Returns the keys of all fields in the configuration. |
|
||||
| `config_keys_read_only` | `List[str]` | `ro` | `N/A` | Returns the keys of all read only fields in the configuration. |
|
||||
| `data_cache_path` | `Optional[pathlib.Path]` | `ro` | `N/A` | Compute data_cache_path based on data_folder_path. |
|
||||
| `data_cache_subpath` | `Optional[pathlib.Path]` | `rw` | `cache` | Sub-path for the EOS cache data directory. |
|
||||
| `data_folder_path` | `Optional[pathlib.Path]` | `rw` | `None` | Path to EOS data directory. |
|
||||
| `data_output_path` | `Optional[pathlib.Path]` | `ro` | `N/A` | Compute data_output_path based on data_folder_path. |
|
||||
| `data_output_subpath` | `Optional[pathlib.Path]` | `rw` | `output` | Sub-path for the EOS output data directory. |
|
||||
| `latitude` | `Optional[float]` | `rw` | `None` | Latitude in decimal degrees, between -90 and 90, north is positive (ISO 19115) (°) |
|
||||
| `longitude` | `Optional[float]` | `rw` | `None` | Longitude in decimal degrees, within -180 to 180 (°) |
|
||||
| `package_root_path` | `<class 'pathlib.Path'>` | `ro` | `N/A` | Compute the package root path. |
|
||||
| `timezone` | `Optional[str]` | `ro` | `N/A` | Compute timezone based on latitude and longitude. |
|
||||
:::
|
||||
|
||||
## Battery Device Simulation Configuration
|
||||
|
||||
:::{table} Battery Device Simulation Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `battery_capacity` | `Optional[int]` | `rw` | `None` | Battery capacity [Wh]. |
|
||||
| `battery_charging_efficiency` | `Optional[float]` | `rw` | `None` | Battery charging efficiency [%]. |
|
||||
| `battery_discharging_efficiency` | `Optional[float]` | `rw` | `None` | Battery discharging efficiency [%]. |
|
||||
| `battery_initial_soc` | `Optional[int]` | `rw` | `None` | Battery initial state of charge [%]. |
|
||||
| `battery_max_charging_power` | `Optional[int]` | `rw` | `None` | Battery maximum charge power [W]. |
|
||||
| `battery_provider` | `Optional[str]` | `rw` | `None` | Id of Battery simulation provider. |
|
||||
| `battery_soc_max` | `Optional[int]` | `rw` | `None` | Battery maximum state of charge [%]. |
|
||||
| `battery_soc_min` | `Optional[int]` | `rw` | `None` | Battery minimum state of charge [%]. |
|
||||
:::
|
||||
|
||||
## Battery Electric Vehicle Device Simulation Configuration
|
||||
|
||||
:::{table} Battery Electric Vehicle Device Simulation Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `bev_capacity` | `Optional[int]` | `rw` | `None` | Battery Electric Vehicle capacity [Wh]. |
|
||||
| `bev_charging_efficiency` | `Optional[float]` | `rw` | `None` | Battery Electric Vehicle charging efficiency [%]. |
|
||||
| `bev_discharging_efficiency` | `Optional[float]` | `rw` | `None` | Battery Electric Vehicle discharging efficiency [%]. |
|
||||
| `bev_initial_soc` | `Optional[int]` | `rw` | `None` | Battery Electric Vehicle initial state of charge [%]. |
|
||||
| `bev_max_charging_power` | `Optional[int]` | `rw` | `None` | Battery Electric Vehicle maximum charge power [W]. |
|
||||
| `bev_provider` | `Optional[str]` | `rw` | `None` | Id of Battery Electric Vehicle simulation provider. |
|
||||
| `bev_soc_max` | `Optional[int]` | `rw` | `None` | Battery Electric Vehicle maximum state of charge [%]. |
|
||||
:::
|
||||
|
||||
## Dishwasher Device Simulation Configuration
|
||||
|
||||
:::{table} Dishwasher Device Simulation Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `dishwasher_consumption` | `Optional[int]` | `rw` | `None` | Dish Washer energy consumption [Wh]. |
|
||||
| `dishwasher_duration` | `Optional[int]` | `rw` | `None` | Dish Washer usage duration [h]. |
|
||||
| `dishwasher_provider` | `Optional[str]` | `rw` | `None` | Id of Dish Washer simulation provider. |
|
||||
:::
|
||||
|
||||
## Electricity Price Prediction Configuration
|
||||
|
||||
:::{table} Electricity Price Prediction Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `elecprice_charges_kwh` | `Optional[float]` | `rw` | `None` | Electricity price charges (€/kWh). |
|
||||
| `elecprice_provider` | `Optional[str]` | `rw` | `None` | Electricity price provider id of provider to be used. |
|
||||
| `elecpriceimport_file_path` | `Union[str, pathlib.Path, NoneType]` | `rw` | `None` | Path to the file to import elecprice data from. |
|
||||
| `elecpriceimport_json` | `Optional[str]` | `rw` | `None` | JSON string, dictionary of electricity price forecast value lists. |
|
||||
:::
|
||||
|
||||
## General Optimization Configuration
|
||||
|
||||
:::{table} General Optimization Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `optimization_ev_available_charge_rates_percent` | `Optional[typing.List[float]]` | `rw` | `[0.0, 0.375, 0.5, 0.625, 0.75, 0.875, 1.0]` | Charge rates available for the EV in percent of maximum charge. |
|
||||
| `optimization_hours` | `Optional[int]` | `rw` | `24` | Number of hours into the future for optimizations. |
|
||||
| `optimization_penalty` | `Optional[int]` | `rw` | `10` | Penalty factor used in optimization. |
|
||||
:::
|
||||
|
||||
## General Prediction Configuration
|
||||
|
||||
:::{table} General Prediction Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `prediction_historic_hours` | `Optional[int]` | `rw` | `48` | Number of hours into the past for historical predictions data |
|
||||
| `prediction_hours` | `Optional[int]` | `rw` | `48` | Number of hours into the future for predictions |
|
||||
:::
|
||||
|
||||
## Inverter Device Simulation Configuration
|
||||
|
||||
:::{table} Inverter Device Simulation Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `inverter_power_max` | `Optional[float]` | `rw` | `None` | Inverter maximum power [W]. |
|
||||
| `inverter_provider` | `Optional[str]` | `rw` | `None` | Id of PV Inverter simulation provider. |
|
||||
:::
|
||||
|
||||
## Load Prediction Configuration
|
||||
|
||||
:::{table} Load Prediction Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `load_import_file_path` | `Union[str, pathlib.Path, NoneType]` | `rw` | `None` | Path to the file to import load data from. |
|
||||
| `load_import_json` | `Optional[str]` | `rw` | `None` | JSON string, dictionary of load forecast value lists. |
|
||||
| `load_provider` | `Optional[str]` | `rw` | `None` | Load provider id of provider to be used. |
|
||||
| `loadakkudoktor_year_energy` | `Optional[float]` | `rw` | `None` | Yearly energy consumption (kWh). |
|
||||
:::
|
||||
|
||||
## Logging Configuration
|
||||
|
||||
:::{table} Logging Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `logging_level_default` | `Optional[str]` | `rw` | `None` | EOS default logging level. |
|
||||
| `logging_level_root` | `<class 'str'>` | `ro` | `N/A` | Root logger logging level. |
|
||||
:::
|
||||
|
||||
## Measurement Configuration
|
||||
|
||||
:::{table} Measurement Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `measurement_load0_name` | `Optional[str]` | `rw` | `None` | Name of the load0 source (e.g. 'Household', 'Heat Pump') |
|
||||
| `measurement_load1_name` | `Optional[str]` | `rw` | `None` | Name of the load1 source (e.g. 'Household', 'Heat Pump') |
|
||||
| `measurement_load2_name` | `Optional[str]` | `rw` | `None` | Name of the load2 source (e.g. 'Household', 'Heat Pump') |
|
||||
| `measurement_load3_name` | `Optional[str]` | `rw` | `None` | Name of the load3 source (e.g. 'Household', 'Heat Pump') |
|
||||
| `measurement_load4_name` | `Optional[str]` | `rw` | `None` | Name of the load4 source (e.g. 'Household', 'Heat Pump') |
|
||||
:::
|
||||
|
||||
## PV Forecast Configuration
|
||||
|
||||
:::{table} PV Forecast Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `pvforecast0_albedo` | `Optional[float]` | `rw` | `None` | Proportion of the light hitting the ground that it reflects back. |
|
||||
| `pvforecast0_inverter_model` | `Optional[str]` | `rw` | `None` | Model of the inverter of this plane. |
|
||||
| `pvforecast0_inverter_paco` | `Optional[int]` | `rw` | `None` | AC power rating of the inverter. [W] |
|
||||
| `pvforecast0_loss` | `Optional[float]` | `rw` | `14.0` | Sum of PV system losses in percent |
|
||||
| `pvforecast0_module_model` | `Optional[str]` | `rw` | `None` | Model of the PV modules of this plane. |
|
||||
| `pvforecast0_modules_per_string` | `Optional[int]` | `rw` | `None` | Number of the PV modules of the strings of this plane. |
|
||||
| `pvforecast0_mountingplace` | `Optional[str]` | `rw` | `free` | Type of mounting for PV system. Options are 'free' for free-standing and 'building' for building-integrated. |
|
||||
| `pvforecast0_optimal_surface_tilt` | `Optional[bool]` | `rw` | `False` | Calculate the optimum tilt angle. Ignored for two-axis tracking. |
|
||||
| `pvforecast0_optimalangles` | `Optional[bool]` | `rw` | `False` | Calculate the optimum tilt and azimuth angles. Ignored for two-axis tracking. |
|
||||
| `pvforecast0_peakpower` | `Optional[float]` | `rw` | `None` | Nominal power of PV system in kW. |
|
||||
| `pvforecast0_pvtechchoice` | `Optional[str]` | `rw` | `crystSi` | PV technology. One of 'crystSi', 'CIS', 'CdTe', 'Unknown'. |
|
||||
| `pvforecast0_strings_per_inverter` | `Optional[int]` | `rw` | `None` | Number of the strings of the inverter of this plane. |
|
||||
| `pvforecast0_surface_azimuth` | `Optional[float]` | `rw` | `None` | Orientation (azimuth angle) of the (fixed) plane. Clockwise from north (north=0, east=90, south=180, west=270). |
|
||||
| `pvforecast0_surface_tilt` | `Optional[float]` | `rw` | `None` | Tilt angle from horizontal plane. Ignored for two-axis tracking. |
|
||||
| `pvforecast0_trackingtype` | `Optional[int]` | `rw` | `None` | Type of suntracking. 0=fixed, 1=single horizontal axis aligned north-south, 2=two-axis tracking, 3=vertical axis tracking, 4=single horizontal axis aligned east-west, 5=single inclined axis aligned north-south. |
|
||||
| `pvforecast0_userhorizon` | `Optional[typing.List[float]]` | `rw` | `None` | Elevation of horizon in degrees, at equally spaced azimuth clockwise from north. |
|
||||
| `pvforecast1_albedo` | `Optional[float]` | `rw` | `None` | Proportion of the light hitting the ground that it reflects back. |
|
||||
| `pvforecast1_inverter_model` | `Optional[str]` | `rw` | `None` | Model of the inverter of this plane. |
|
||||
| `pvforecast1_inverter_paco` | `Optional[int]` | `rw` | `None` | AC power rating of the inverter. [W] |
|
||||
| `pvforecast1_loss` | `Optional[float]` | `rw` | `14.0` | Sum of PV system losses in percent |
|
||||
| `pvforecast1_module_model` | `Optional[str]` | `rw` | `None` | Model of the PV modules of this plane. |
|
||||
| `pvforecast1_modules_per_string` | `Optional[int]` | `rw` | `None` | Number of the PV modules of the strings of this plane. |
|
||||
| `pvforecast1_mountingplace` | `Optional[str]` | `rw` | `free` | Type of mounting for PV system. Options are 'free' for free-standing and 'building' for building-integrated. |
|
||||
| `pvforecast1_optimal_surface_tilt` | `Optional[bool]` | `rw` | `False` | Calculate the optimum tilt angle. Ignored for two-axis tracking. |
|
||||
| `pvforecast1_optimalangles` | `Optional[bool]` | `rw` | `False` | Calculate the optimum tilt and azimuth angles. Ignored for two-axis tracking. |
|
||||
| `pvforecast1_peakpower` | `Optional[float]` | `rw` | `None` | Nominal power of PV system in kW. |
|
||||
| `pvforecast1_pvtechchoice` | `Optional[str]` | `rw` | `crystSi` | PV technology. One of 'crystSi', 'CIS', 'CdTe', 'Unknown'. |
|
||||
| `pvforecast1_strings_per_inverter` | `Optional[int]` | `rw` | `None` | Number of the strings of the inverter of this plane. |
|
||||
| `pvforecast1_surface_azimuth` | `Optional[float]` | `rw` | `None` | Orientation (azimuth angle) of the (fixed) plane. Clockwise from north (north=0, east=90, south=180, west=270). |
|
||||
| `pvforecast1_surface_tilt` | `Optional[float]` | `rw` | `None` | Tilt angle from horizontal plane. Ignored for two-axis tracking. |
|
||||
| `pvforecast1_trackingtype` | `Optional[int]` | `rw` | `None` | Type of suntracking. 0=fixed, 1=single horizontal axis aligned north-south, 2=two-axis tracking, 3=vertical axis tracking, 4=single horizontal axis aligned east-west, 5=single inclined axis aligned north-south. |
|
||||
| `pvforecast1_userhorizon` | `Optional[typing.List[float]]` | `rw` | `None` | Elevation of horizon in degrees, at equally spaced azimuth clockwise from north. |
|
||||
| `pvforecast2_albedo` | `Optional[float]` | `rw` | `None` | Proportion of the light hitting the ground that it reflects back. |
|
||||
| `pvforecast2_inverter_model` | `Optional[str]` | `rw` | `None` | Model of the inverter of this plane. |
|
||||
| `pvforecast2_inverter_paco` | `Optional[int]` | `rw` | `None` | AC power rating of the inverter. [W] |
|
||||
| `pvforecast2_loss` | `Optional[float]` | `rw` | `14.0` | Sum of PV system losses in percent |
|
||||
| `pvforecast2_module_model` | `Optional[str]` | `rw` | `None` | Model of the PV modules of this plane. |
|
||||
| `pvforecast2_modules_per_string` | `Optional[int]` | `rw` | `None` | Number of the PV modules of the strings of this plane. |
|
||||
| `pvforecast2_mountingplace` | `Optional[str]` | `rw` | `free` | Type of mounting for PV system. Options are 'free' for free-standing and 'building' for building-integrated. |
|
||||
| `pvforecast2_optimal_surface_tilt` | `Optional[bool]` | `rw` | `False` | Calculate the optimum tilt angle. Ignored for two-axis tracking. |
|
||||
| `pvforecast2_optimalangles` | `Optional[bool]` | `rw` | `False` | Calculate the optimum tilt and azimuth angles. Ignored for two-axis tracking. |
|
||||
| `pvforecast2_peakpower` | `Optional[float]` | `rw` | `None` | Nominal power of PV system in kW. |
|
||||
| `pvforecast2_pvtechchoice` | `Optional[str]` | `rw` | `crystSi` | PV technology. One of 'crystSi', 'CIS', 'CdTe', 'Unknown'. |
|
||||
| `pvforecast2_strings_per_inverter` | `Optional[int]` | `rw` | `None` | Number of the strings of the inverter of this plane. |
|
||||
| `pvforecast2_surface_azimuth` | `Optional[float]` | `rw` | `None` | Orientation (azimuth angle) of the (fixed) plane. Clockwise from north (north=0, east=90, south=180, west=270). |
|
||||
| `pvforecast2_surface_tilt` | `Optional[float]` | `rw` | `None` | Tilt angle from horizontal plane. Ignored for two-axis tracking. |
|
||||
| `pvforecast2_trackingtype` | `Optional[int]` | `rw` | `None` | Type of suntracking. 0=fixed, 1=single horizontal axis aligned north-south, 2=two-axis tracking, 3=vertical axis tracking, 4=single horizontal axis aligned east-west, 5=single inclined axis aligned north-south. |
|
||||
| `pvforecast2_userhorizon` | `Optional[typing.List[float]]` | `rw` | `None` | Elevation of horizon in degrees, at equally spaced azimuth clockwise from north. |
|
||||
| `pvforecast3_albedo` | `Optional[float]` | `rw` | `None` | Proportion of the light hitting the ground that it reflects back. |
|
||||
| `pvforecast3_inverter_model` | `Optional[str]` | `rw` | `None` | Model of the inverter of this plane. |
|
||||
| `pvforecast3_inverter_paco` | `Optional[int]` | `rw` | `None` | AC power rating of the inverter. [W] |
|
||||
| `pvforecast3_loss` | `Optional[float]` | `rw` | `14.0` | Sum of PV system losses in percent |
|
||||
| `pvforecast3_module_model` | `Optional[str]` | `rw` | `None` | Model of the PV modules of this plane. |
|
||||
| `pvforecast3_modules_per_string` | `Optional[int]` | `rw` | `None` | Number of the PV modules of the strings of this plane. |
|
||||
| `pvforecast3_mountingplace` | `Optional[str]` | `rw` | `free` | Type of mounting for PV system. Options are 'free' for free-standing and 'building' for building-integrated. |
|
||||
| `pvforecast3_optimal_surface_tilt` | `Optional[bool]` | `rw` | `False` | Calculate the optimum tilt angle. Ignored for two-axis tracking. |
|
||||
| `pvforecast3_optimalangles` | `Optional[bool]` | `rw` | `False` | Calculate the optimum tilt and azimuth angles. Ignored for two-axis tracking. |
|
||||
| `pvforecast3_peakpower` | `Optional[float]` | `rw` | `None` | Nominal power of PV system in kW. |
|
||||
| `pvforecast3_pvtechchoice` | `Optional[str]` | `rw` | `crystSi` | PV technology. One of 'crystSi', 'CIS', 'CdTe', 'Unknown'. |
|
||||
| `pvforecast3_strings_per_inverter` | `Optional[int]` | `rw` | `None` | Number of the strings of the inverter of this plane. |
|
||||
| `pvforecast3_surface_azimuth` | `Optional[float]` | `rw` | `None` | Orientation (azimuth angle) of the (fixed) plane. Clockwise from north (north=0, east=90, south=180, west=270). |
|
||||
| `pvforecast3_surface_tilt` | `Optional[float]` | `rw` | `None` | Tilt angle from horizontal plane. Ignored for two-axis tracking. |
|
||||
| `pvforecast3_trackingtype` | `Optional[int]` | `rw` | `None` | Type of suntracking. 0=fixed, 1=single horizontal axis aligned north-south, 2=two-axis tracking, 3=vertical axis tracking, 4=single horizontal axis aligned east-west, 5=single inclined axis aligned north-south. |
|
||||
| `pvforecast3_userhorizon` | `Optional[typing.List[float]]` | `rw` | `None` | Elevation of horizon in degrees, at equally spaced azimuth clockwise from north. |
|
||||
| `pvforecast4_albedo` | `Optional[float]` | `rw` | `None` | Proportion of the light hitting the ground that it reflects back. |
|
||||
| `pvforecast4_inverter_model` | `Optional[str]` | `rw` | `None` | Model of the inverter of this plane. |
|
||||
| `pvforecast4_inverter_paco` | `Optional[int]` | `rw` | `None` | AC power rating of the inverter. [W] |
|
||||
| `pvforecast4_loss` | `Optional[float]` | `rw` | `14.0` | Sum of PV system losses in percent |
|
||||
| `pvforecast4_module_model` | `Optional[str]` | `rw` | `None` | Model of the PV modules of this plane. |
|
||||
| `pvforecast4_modules_per_string` | `Optional[int]` | `rw` | `None` | Number of the PV modules of the strings of this plane. |
|
||||
| `pvforecast4_mountingplace` | `Optional[str]` | `rw` | `free` | Type of mounting for PV system. Options are 'free' for free-standing and 'building' for building-integrated. |
|
||||
| `pvforecast4_optimal_surface_tilt` | `Optional[bool]` | `rw` | `False` | Calculate the optimum tilt angle. Ignored for two-axis tracking. |
|
||||
| `pvforecast4_optimalangles` | `Optional[bool]` | `rw` | `False` | Calculate the optimum tilt and azimuth angles. Ignored for two-axis tracking. |
|
||||
| `pvforecast4_peakpower` | `Optional[float]` | `rw` | `None` | Nominal power of PV system in kW. |
|
||||
| `pvforecast4_pvtechchoice` | `Optional[str]` | `rw` | `crystSi` | PV technology. One of 'crystSi', 'CIS', 'CdTe', 'Unknown'. |
|
||||
| `pvforecast4_strings_per_inverter` | `Optional[int]` | `rw` | `None` | Number of the strings of the inverter of this plane. |
|
||||
| `pvforecast4_surface_azimuth` | `Optional[float]` | `rw` | `None` | Orientation (azimuth angle) of the (fixed) plane. Clockwise from north (north=0, east=90, south=180, west=270). |
|
||||
| `pvforecast4_surface_tilt` | `Optional[float]` | `rw` | `None` | Tilt angle from horizontal plane. Ignored for two-axis tracking. |
|
||||
| `pvforecast4_trackingtype` | `Optional[int]` | `rw` | `None` | Type of suntracking. 0=fixed, 1=single horizontal axis aligned north-south, 2=two-axis tracking, 3=vertical axis tracking, 4=single horizontal axis aligned east-west, 5=single inclined axis aligned north-south. |
|
||||
| `pvforecast4_userhorizon` | `Optional[typing.List[float]]` | `rw` | `None` | Elevation of horizon in degrees, at equally spaced azimuth clockwise from north. |
|
||||
| `pvforecast5_albedo` | `Optional[float]` | `rw` | `None` | Proportion of the light hitting the ground that it reflects back. |
|
||||
| `pvforecast5_inverter_model` | `Optional[str]` | `rw` | `None` | Model of the inverter of this plane. |
|
||||
| `pvforecast5_inverter_paco` | `Optional[int]` | `rw` | `None` | AC power rating of the inverter. [W] |
|
||||
| `pvforecast5_loss` | `Optional[float]` | `rw` | `14.0` | Sum of PV system losses in percent |
|
||||
| `pvforecast5_module_model` | `Optional[str]` | `rw` | `None` | Model of the PV modules of this plane. |
|
||||
| `pvforecast5_modules_per_string` | `Optional[int]` | `rw` | `None` | Number of the PV modules of the strings of this plane. |
|
||||
| `pvforecast5_mountingplace` | `Optional[str]` | `rw` | `free` | Type of mounting for PV system. Options are 'free' for free-standing and 'building' for building-integrated. |
|
||||
| `pvforecast5_optimal_surface_tilt` | `Optional[bool]` | `rw` | `False` | Calculate the optimum tilt angle. Ignored for two-axis tracking. |
|
||||
| `pvforecast5_optimalangles` | `Optional[bool]` | `rw` | `False` | Calculate the optimum tilt and azimuth angles. Ignored for two-axis tracking. |
|
||||
| `pvforecast5_peakpower` | `Optional[float]` | `rw` | `None` | Nominal power of PV system in kW. |
|
||||
| `pvforecast5_pvtechchoice` | `Optional[str]` | `rw` | `crystSi` | PV technology. One of 'crystSi', 'CIS', 'CdTe', 'Unknown'. |
|
||||
| `pvforecast5_strings_per_inverter` | `Optional[int]` | `rw` | `None` | Number of the strings of the inverter of this plane. |
|
||||
| `pvforecast5_surface_azimuth` | `Optional[float]` | `rw` | `None` | Orientation (azimuth angle) of the (fixed) plane. Clockwise from north (north=0, east=90, south=180, west=270). |
|
||||
| `pvforecast5_surface_tilt` | `Optional[float]` | `rw` | `None` | Tilt angle from horizontal plane. Ignored for two-axis tracking. |
|
||||
| `pvforecast5_trackingtype` | `Optional[int]` | `rw` | `None` | Type of suntracking. 0=fixed, 1=single horizontal axis aligned north-south, 2=two-axis tracking, 3=vertical axis tracking, 4=single horizontal axis aligned east-west, 5=single inclined axis aligned north-south. |
|
||||
| `pvforecast5_userhorizon` | `Optional[typing.List[float]]` | `rw` | `None` | Elevation of horizon in degrees, at equally spaced azimuth clockwise from north. |
|
||||
| `pvforecast_planes` | `List[str]` | `ro` | `N/A` | Compute a list of active planes. |
|
||||
| `pvforecast_planes_azimuth` | `List[float]` | `ro` | `N/A` | Compute a list of the azimuths per active planes. |
|
||||
| `pvforecast_planes_inverter_paco` | `Any` | `ro` | `N/A` | Compute a list of the maximum power rating of the inverter per active planes. |
|
||||
| `pvforecast_planes_peakpower` | `List[float]` | `ro` | `N/A` | Compute a list of the peak power per active planes. |
|
||||
| `pvforecast_planes_tilt` | `List[float]` | `ro` | `N/A` | Compute a list of the tilts per active planes. |
|
||||
| `pvforecast_planes_userhorizon` | `Any` | `ro` | `N/A` | Compute a list of the user horizon per active planes. |
|
||||
| `pvforecast_provider` | `Optional[str]` | `rw` | `None` | PVForecast provider id of provider to be used. |
|
||||
| `pvforecastimport_file_path` | `Union[str, pathlib.Path, NoneType]` | `rw` | `None` | Path to the file to import PV forecast data from. |
|
||||
| `pvforecastimport_json` | `Optional[str]` | `rw` | `None` | JSON string, dictionary of PV forecast value lists. |
|
||||
:::
|
||||
|
||||
## Server Configuration
|
||||
|
||||
:::{table} Server Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `server_fastapi_host` | `Optional[pydantic.networks.IPvAnyAddress]` | `rw` | `0.0.0.0` | FastAPI server IP address. |
|
||||
| `server_fastapi_port` | `Optional[int]` | `rw` | `8503` | FastAPI server IP port number. |
|
||||
| `server_fastapi_startup_server_fasthtml` | `Optional[bool]` | `rw` | `True` | FastAPI server to startup application FastHTML server. |
|
||||
| `server_fastapi_verbose` | `Optional[bool]` | `rw` | `False` | Enable debug output |
|
||||
| `server_fasthtml_host` | `Optional[pydantic.networks.IPvAnyAddress]` | `rw` | `0.0.0.0` | FastHTML server IP address. |
|
||||
| `server_fasthtml_port` | `Optional[int]` | `rw` | `8504` | FastHTML server IP port number. |
|
||||
:::
|
||||
|
||||
## Weather Forecast Configuration
|
||||
|
||||
:::{table} Weather Forecast Configuration
|
||||
:widths: 10 10 5 5 30
|
||||
:align: left
|
||||
|
||||
| Name | Type | Read-Only | Default | Description |
|
||||
| ---- | ---- | --------- | ------- | ----------- |
|
||||
| `weather_provider` | `Optional[str]` | `rw` | `None` | Weather provider id of provider to be used. |
|
||||
| `weatherimport_file_path` | `Union[str, pathlib.Path, NoneType]` | `rw` | `None` | Path to the file to import weather data from. |
|
||||
| `weatherimport_json` | `Optional[str]` | `rw` | `None` | JSON string, dictionary of weather forecast value lists. |
|
||||
:::
|
||||
@ -10,7 +10,7 @@
|
||||
|
||||
## POST /gesamtlast
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_gesamtlast_gesamtlast_post), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_gesamtlast_gesamtlast_post)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_gesamtlast_gesamtlast_post), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_gesamtlast_gesamtlast_post)
|
||||
|
||||
Fastapi Gesamtlast
|
||||
|
||||
@ -46,7 +46,7 @@ Note:
|
||||
|
||||
## GET /gesamtlast_simple
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_gesamtlast_simple_gesamtlast_simple_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_gesamtlast_simple_gesamtlast_simple_get)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_gesamtlast_simple_gesamtlast_simple_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_gesamtlast_simple_gesamtlast_simple_get)
|
||||
|
||||
Fastapi Gesamtlast Simple
|
||||
|
||||
@ -80,7 +80,7 @@ Note:
|
||||
|
||||
## POST /optimize
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_optimize_optimize_post), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_optimize_optimize_post)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_optimize_optimize_post), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_optimize_optimize_post)
|
||||
|
||||
Fastapi Optimize
|
||||
|
||||
@ -104,7 +104,7 @@ Fastapi Optimize
|
||||
|
||||
## GET /pvforecast
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_pvforecast_pvforecast_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_pvforecast_pvforecast_get)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_pvforecast_pvforecast_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_pvforecast_pvforecast_get)
|
||||
|
||||
Fastapi Pvforecast
|
||||
|
||||
@ -133,7 +133,7 @@ Note:
|
||||
|
||||
## GET /strompreis
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_strompreis_strompreis_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_strompreis_strompreis_get)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_strompreis_strompreis_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_strompreis_strompreis_get)
|
||||
|
||||
Fastapi Strompreis
|
||||
|
||||
@ -163,7 +163,7 @@ Note:
|
||||
|
||||
## GET /v1/config
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_get_v1_config_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_get_v1_config_get)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_get_v1_config_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_get_v1_config_get)
|
||||
|
||||
Fastapi Config Get
|
||||
|
||||
@ -182,7 +182,7 @@ Returns:
|
||||
|
||||
## PUT /v1/config
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_put_v1_config_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_put_v1_config_put)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_put_v1_config_put), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_put_v1_config_put)
|
||||
|
||||
Fastapi Config Put
|
||||
|
||||
@ -516,7 +516,7 @@ Returns:
|
||||
|
||||
## GET /v1/config/file
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_file_get_v1_config_file_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_file_get_v1_config_file_get)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_file_get_v1_config_file_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_file_get_v1_config_file_get)
|
||||
|
||||
Fastapi Config File Get
|
||||
|
||||
@ -535,7 +535,7 @@ Returns:
|
||||
|
||||
## PUT /v1/config/file
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_file_put_v1_config_file_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_file_put_v1_config_file_put)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_file_put_v1_config_file_put), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_file_put_v1_config_file_put)
|
||||
|
||||
Fastapi Config File Put
|
||||
|
||||
@ -554,7 +554,7 @@ Returns:
|
||||
|
||||
## POST /v1/config/update
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_update_post_v1_config_update_post), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_update_post_v1_config_update_post)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_update_post_v1_config_update_post), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_update_post_v1_config_update_post)
|
||||
|
||||
Fastapi Config Update Post
|
||||
|
||||
@ -573,7 +573,7 @@ Returns:
|
||||
|
||||
## PUT /v1/config/value
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_value_put_v1_config_value_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_value_put_v1_config_value_put)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_value_put_v1_config_value_put), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_value_put_v1_config_value_put)
|
||||
|
||||
Fastapi Config Value Put
|
||||
|
||||
@ -604,7 +604,7 @@ Returns:
|
||||
|
||||
## PUT /v1/measurement/data
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_data_put_v1_measurement_data_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_data_put_v1_measurement_data_put)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_data_put_v1_measurement_data_put), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_data_put_v1_measurement_data_put)
|
||||
|
||||
Fastapi Measurement Data Put
|
||||
|
||||
@ -628,7 +628,7 @@ Merge the measurement data given as datetime data into EOS measurements.
|
||||
|
||||
## PUT /v1/measurement/dataframe
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_dataframe_put_v1_measurement_dataframe_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_dataframe_put_v1_measurement_dataframe_put)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_dataframe_put_v1_measurement_dataframe_put), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_dataframe_put_v1_measurement_dataframe_put)
|
||||
|
||||
Fastapi Measurement Dataframe Put
|
||||
|
||||
@ -652,7 +652,7 @@ Merge the measurement data given as dataframe into EOS measurements.
|
||||
|
||||
## GET /v1/measurement/keys
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_keys_get_v1_measurement_keys_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_keys_get_v1_measurement_keys_get)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_keys_get_v1_measurement_keys_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_keys_get_v1_measurement_keys_get)
|
||||
|
||||
Fastapi Measurement Keys Get
|
||||
|
||||
@ -668,7 +668,7 @@ Get a list of available measurement keys.
|
||||
|
||||
## GET /v1/measurement/load-mr/series/by-name
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_load_mr_series_by_name_get_v1_measurement_load-mr_series_by-name_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_load_mr_series_by_name_get_v1_measurement_load-mr_series_by-name_get)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_load_mr_series_by_name_get_v1_measurement_load-mr_series_by-name_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_load_mr_series_by_name_get_v1_measurement_load-mr_series_by-name_get)
|
||||
|
||||
Fastapi Measurement Load Mr Series By Name Get
|
||||
|
||||
@ -690,7 +690,7 @@ Get the meter reading of given load name as series.
|
||||
|
||||
## PUT /v1/measurement/load-mr/series/by-name
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_load_mr_series_by_name_put_v1_measurement_load-mr_series_by-name_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_load_mr_series_by_name_put_v1_measurement_load-mr_series_by-name_put)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_load_mr_series_by_name_put_v1_measurement_load-mr_series_by-name_put), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_load_mr_series_by_name_put_v1_measurement_load-mr_series_by-name_put)
|
||||
|
||||
Fastapi Measurement Load Mr Series By Name Put
|
||||
|
||||
@ -718,7 +718,7 @@ Merge the meter readings series of given load name into EOS measurements at give
|
||||
|
||||
## PUT /v1/measurement/load-mr/value/by-name
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_load_mr_value_by_name_put_v1_measurement_load-mr_value_by-name_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_load_mr_value_by_name_put_v1_measurement_load-mr_value_by-name_put)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_load_mr_value_by_name_put_v1_measurement_load-mr_value_by-name_put), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_load_mr_value_by_name_put_v1_measurement_load-mr_value_by-name_put)
|
||||
|
||||
Fastapi Measurement Load Mr Value By Name Put
|
||||
|
||||
@ -744,7 +744,7 @@ Merge the meter reading of given load name and value into EOS measurements at gi
|
||||
|
||||
## GET /v1/measurement/series
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_series_get_v1_measurement_series_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_series_get_v1_measurement_series_get)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_series_get_v1_measurement_series_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_series_get_v1_measurement_series_get)
|
||||
|
||||
Fastapi Measurement Series Get
|
||||
|
||||
@ -766,7 +766,7 @@ Get the measurements of given key as series.
|
||||
|
||||
## PUT /v1/measurement/series
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_series_put_v1_measurement_series_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_series_put_v1_measurement_series_put)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_series_put_v1_measurement_series_put), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_series_put_v1_measurement_series_put)
|
||||
|
||||
Fastapi Measurement Series Put
|
||||
|
||||
@ -794,7 +794,7 @@ Merge measurement given as series into given key.
|
||||
|
||||
## PUT /v1/measurement/value
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_value_put_v1_measurement_value_put), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_value_put_v1_measurement_value_put)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_measurement_value_put_v1_measurement_value_put), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_measurement_value_put_v1_measurement_value_put)
|
||||
|
||||
Fastapi Measurement Value Put
|
||||
|
||||
@ -820,7 +820,7 @@ Merge the measurement of given key and value into EOS measurements at given date
|
||||
|
||||
## GET /v1/prediction/keys
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_keys_get_v1_prediction_keys_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_keys_get_v1_prediction_keys_get)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_keys_get_v1_prediction_keys_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_keys_get_v1_prediction_keys_get)
|
||||
|
||||
Fastapi Prediction Keys Get
|
||||
|
||||
@ -836,7 +836,7 @@ Get a list of available prediction keys.
|
||||
|
||||
## GET /v1/prediction/list
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_list_get_v1_prediction_list_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_list_get_v1_prediction_list_get)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_list_get_v1_prediction_list_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_list_get_v1_prediction_list_get)
|
||||
|
||||
Fastapi Prediction List Get
|
||||
|
||||
@ -873,7 +873,7 @@ Args:
|
||||
|
||||
## GET /v1/prediction/series
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_series_get_v1_prediction_series_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_series_get_v1_prediction_series_get)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_series_get_v1_prediction_series_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_series_get_v1_prediction_series_get)
|
||||
|
||||
Fastapi Prediction Series Get
|
||||
|
||||
@ -906,7 +906,7 @@ Args:
|
||||
|
||||
## POST /v1/prediction/update
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_update_v1_prediction_update_post), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_update_v1_prediction_update_post)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_update_v1_prediction_update_post), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_update_v1_prediction_update_post)
|
||||
|
||||
Fastapi Prediction Update
|
||||
|
||||
@ -936,7 +936,7 @@ Args:
|
||||
|
||||
## POST /v1/prediction/update/{provider_id}
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_update_provider_v1_prediction_update__provider_id__post), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_update_provider_v1_prediction_update__provider_id__post)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_update_provider_v1_prediction_update__provider_id__post), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_update_provider_v1_prediction_update__provider_id__post)
|
||||
|
||||
Fastapi Prediction Update Provider
|
||||
|
||||
@ -969,7 +969,7 @@ Args:
|
||||
|
||||
## GET /visualization_results.pdf
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/get_pdf_visualization_results_pdf_get), [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/get_pdf_visualization_results_pdf_get)
|
||||
**Links**: [local](http://localhost:8503/docs#/default/get_pdf_visualization_results_pdf_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/get_pdf_visualization_results_pdf_get)
|
||||
|
||||
Get Pdf
|
||||
|
||||
@ -84,6 +84,8 @@ and default settings are loaded into it.
|
||||
Some of the `configuration keys` have default values by definition. For most of the
|
||||
`configuration keys` the default value is just `None`, which means no default value.
|
||||
|
||||
```{eval-sh}
|
||||
./scripts/generate_config_md.py | ./scripts/extract_markdown.py --input-stdin --heading-level 1
|
||||
```{include} /_generated/config.md
|
||||
:heading-offset: 1
|
||||
:relative-docs: ..
|
||||
:relative-images:
|
||||
```
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
|
||||
# Server API
|
||||
|
||||
```{eval-sh}
|
||||
./scripts/generate_openapi_md.py | ./scripts/extract_markdown.py --input-stdin --start-line "**Version**:"
|
||||
```{include} /_generated/openapi.md
|
||||
:start-line: 2
|
||||
:relative-docs: ..
|
||||
:relative-images:
|
||||
```
|
||||
|
||||
@ -24,7 +24,7 @@ extensions = [
|
||||
"sphinx.ext.napoleon",
|
||||
"sphinx_rtd_theme",
|
||||
"myst_parser",
|
||||
"sphinxcontrib.eval",
|
||||
"sphinx_tabs.tabs",
|
||||
]
|
||||
|
||||
templates_path = ["_templates"]
|
||||
|
||||
@ -1,3 +1,4 @@
|
||||
```{eval-sh}
|
||||
./scripts/extract_markdown.py --input-file CONTRIBUTING.md
|
||||
```{include} ../../CONTRIBUTING.md
|
||||
:relative-docs: ../
|
||||
:relative-images:
|
||||
```
|
||||
|
||||
@ -1,5 +1,109 @@
|
||||
# Getting Started
|
||||
|
||||
```{eval-sh}
|
||||
./scripts/extract_markdown.py --input-file README.md --start-line "## Getting Involved"
|
||||
## Installation
|
||||
|
||||
The project requires Python 3.10 or newer. Currently there are no official packages or images published.
|
||||
|
||||
Following sections describe how to locally start the EOS server on `http://localhost:8503`.
|
||||
|
||||
### Run from source
|
||||
|
||||
Install the dependencies in a virtual environment:
|
||||
|
||||
```{eval-rst}
|
||||
.. tabs::
|
||||
|
||||
.. tab:: Windows
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
python -m venv .venv
|
||||
.venv\Scripts\pip install -r requirements.txt
|
||||
|
||||
.. tab:: Linux
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python -m venv .venv
|
||||
.venv/bin/pip install -r requirements.txt
|
||||
|
||||
```
|
||||
|
||||
Start the EOS fastapi server:
|
||||
|
||||
```{eval-rst}
|
||||
.. tabs::
|
||||
|
||||
.. tab:: Windows
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
.venv\Scripts\fastapi run src/akkudoktoreos/server/fastapi_server.py
|
||||
|
||||
.. tab:: Linux
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
.venv/bin/fastapi run src/akkudoktoreos/server/fastapi_server.py
|
||||
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```{eval-rst}
|
||||
.. tabs::
|
||||
|
||||
.. tab:: Windows
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
docker compose up --build
|
||||
|
||||
.. tab:: Linux
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker compose up --build
|
||||
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
This project uses the `EOS.config.json` file to manage configuration settings.
|
||||
|
||||
### Default Configuration
|
||||
|
||||
A default configuration file `default.config.json` is provided. This file contains all the necessary configuration keys with their default values.
|
||||
|
||||
### Custom Configuration
|
||||
|
||||
Users can specify a custom configuration directory by setting the environment variable `EOS_DIR`.
|
||||
|
||||
- If the directory specified by `EOS_DIR` contains an existing `config.json` file, the application will use this configuration file.
|
||||
- If the `EOS.config.json` file does not exist in the specified directory, the `default.config.json` file will be copied to the directory as `EOS.config.json`.
|
||||
|
||||
### Configuration Updates
|
||||
|
||||
If the configuration keys in the `EOS.config.json` file are missing or different from those in `default.config.json`, they will be automatically updated to match the default settings, ensuring that all required keys are present.
|
||||
|
||||
## Classes and Functionalities
|
||||
|
||||
This project uses various classes to simulate and optimize the components of an energy system. Each class represents a specific aspect of the system, as described below:
|
||||
|
||||
- `Battery`: Simulates a battery storage system, including capacity, state of charge, and now charge and discharge losses.
|
||||
|
||||
- `PVForecast`: Provides forecast data for photovoltaic generation, based on weather data and historical generation data.
|
||||
|
||||
- `Load`: Models the load requirements of a household or business, enabling the prediction of future energy demand.
|
||||
|
||||
- `Heatpump`: Simulates a heat pump, including its energy consumption and efficiency under various operating conditions.
|
||||
|
||||
- `Strompreis`: Provides information on electricity prices, enabling optimization of energy consumption and generation based on tariff information.
|
||||
|
||||
- `EMS`: The Energy Management System (EMS) coordinates the interaction between the various components, performs optimization, and simulates the operation of the entire energy system.
|
||||
|
||||
These classes work together to enable a detailed simulation and optimization of the energy system. For each class, specific parameters and settings can be adjusted to test different scenarios and strategies.
|
||||
|
||||
### Customization and Extension
|
||||
|
||||
Each class is designed to be easily customized and extended to integrate additional functions or improvements. For example, new methods can be added for more accurate modeling of PV system or battery behavior. Developers are invited to modify and extend the system according to their needs.
|
||||
|
||||
17902
openapi.json
17902
openapi.json
File diff suppressed because it is too large
Load Diff
@ -1,9 +1,10 @@
|
||||
-r requirements.txt
|
||||
gitpython==3.1.44
|
||||
linkify-it-py==2.0.3
|
||||
myst-parser==4.0.0
|
||||
sphinx==8.1.3
|
||||
sphinx_rtd_theme==3.0.2
|
||||
sphinxcontrib-eval==0.0.3
|
||||
sphinx-tabs==3.4.7
|
||||
pytest==8.3.4
|
||||
pytest-cov==6.0.0
|
||||
pytest-xprocess==1.0.2
|
||||
|
||||
@ -127,6 +127,10 @@ def generate_config_md() -> str:
|
||||
if non_prefixed_configs:
|
||||
markdown += generate_config_table_md(non_prefixed_configs, "Other Configuration Values")
|
||||
|
||||
# Assure the is no double \n at end of file
|
||||
markdown = markdown.rstrip("\n")
|
||||
markdown += "\n"
|
||||
|
||||
return markdown
|
||||
|
||||
|
||||
|
||||
@ -5,6 +5,8 @@ import argparse
|
||||
import json
|
||||
import sys
|
||||
|
||||
import git
|
||||
|
||||
if __package__ is None or __package__ == "":
|
||||
# uses current directory visibility
|
||||
import generate_openapi
|
||||
@ -13,6 +15,47 @@ else:
|
||||
from . import generate_openapi
|
||||
|
||||
|
||||
def akkudoktoreos_base_branch():
|
||||
"""Find the remote branch from the Akkudoktor-EOS repository that the current branch is based on.
|
||||
|
||||
This function searches through all branches in the Akkudoktor-EOS remote
|
||||
to find the first commit of the remote branch taht is in the current branch and returns the name
|
||||
of the remote branch (without the remote name).
|
||||
|
||||
Returns:
|
||||
str: The name of the remote branch (without the remote name)
|
||||
that the first commit of the current branch is based on.
|
||||
Returns None if no matching remote branch is found.
|
||||
"""
|
||||
repo = git.Repo(__file__, search_parent_directories=True)
|
||||
|
||||
# Get the current branch
|
||||
try:
|
||||
current_branch = repo.active_branch.name
|
||||
except:
|
||||
# Maybe detached branch that has no name
|
||||
return None
|
||||
|
||||
first_commit = next(repo.iter_commits(current_branch, max_count=1)).hexsha
|
||||
|
||||
# Iterate over all remote branches to find the first commit
|
||||
for remote in repo.remotes:
|
||||
if "https://github.com/Akkudoktor-EOS" in remote.url:
|
||||
# Only search for Akkudoktor-EOS
|
||||
for ref in remote.refs:
|
||||
try:
|
||||
# Check if the first commit of the current branch is in the remote branch history
|
||||
commits = list(repo.iter_commits(ref.name))
|
||||
if any(commit.hexsha == first_commit for commit in commits):
|
||||
# Remove remote name from the branch name
|
||||
branch_name = "/".join(ref.name.split("/")[1:])
|
||||
return branch_name
|
||||
except git.exc.GitCommandError:
|
||||
continue
|
||||
|
||||
return None
|
||||
|
||||
|
||||
def extract_info(openapi_json: dict) -> dict:
|
||||
"""Extract basic information from OpenAPI JSON.
|
||||
|
||||
@ -113,13 +156,14 @@ def format_responses(responses: dict) -> str:
|
||||
return markdown
|
||||
|
||||
|
||||
def format_endpoint(path: str, method: str, details: dict) -> str:
|
||||
def format_endpoint(path: str, method: str, details: dict, devel: bool = False) -> str:
|
||||
"""Format a single endpoint's details for the Markdown.
|
||||
|
||||
Args:
|
||||
path (str): The endpoint path.
|
||||
method (str): The HTTP method.
|
||||
details (dict): The details of the endpoint.
|
||||
devel (bool): Include development output.
|
||||
|
||||
Returns:
|
||||
str: The formatted endpoint section in Markdown.
|
||||
@ -140,8 +184,8 @@ def format_endpoint(path: str, method: str, details: dict) -> str:
|
||||
"[local](http://localhost:8503/docs#/default/" + link_summary + link_path + link_method
|
||||
)
|
||||
# [swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_strompreis_strompreis_get)
|
||||
swagger_path = (
|
||||
"[swagger](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/"
|
||||
akkudoktoreos_main_path = (
|
||||
"[eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/"
|
||||
+ link_summary
|
||||
+ link_path
|
||||
+ link_method
|
||||
@ -149,7 +193,19 @@ def format_endpoint(path: str, method: str, details: dict) -> str:
|
||||
|
||||
markdown = f"## {method.upper()} {path}\n\n"
|
||||
|
||||
markdown += f"**Links**: {local_path}, {swagger_path}\n\n"
|
||||
markdown += f"**Links**: {local_path}, {akkudoktoreos_main_path}"
|
||||
if devel:
|
||||
# Add link to akkudoktor branch the development has used
|
||||
akkudoktor_branch = akkudoktoreos_base_branch()
|
||||
if akkudoktor_branch is not None:
|
||||
akkudoktoreos_base_path = (
|
||||
f"[devel](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/{akkudoktor_branch}/openapi.json#/default/"
|
||||
+ link_summary
|
||||
+ link_path
|
||||
+ link_method
|
||||
)
|
||||
markdown += f", {akkudoktoreos_base_path}"
|
||||
markdown += "\n\n"
|
||||
|
||||
summary = details.get("summary", None)
|
||||
if summary:
|
||||
@ -169,11 +225,12 @@ def format_endpoint(path: str, method: str, details: dict) -> str:
|
||||
return markdown
|
||||
|
||||
|
||||
def openapi_to_markdown(openapi_json: dict) -> str:
|
||||
def openapi_to_markdown(openapi_json: dict, devel: bool = False) -> str:
|
||||
"""Convert OpenAPI JSON specification to a Markdown representation.
|
||||
|
||||
Args:
|
||||
openapi_json (dict): The OpenAPI specification as a Python dictionary.
|
||||
devel (bool): Include development output.
|
||||
|
||||
Returns:
|
||||
str: The Markdown representation of the OpenAPI spec.
|
||||
@ -216,6 +273,9 @@ def generate_openapi_md() -> str:
|
||||
def main():
|
||||
"""Main function to run the generation of the OpenAPI specification as Markdown."""
|
||||
parser = argparse.ArgumentParser(description="Generate OpenAPI Specification as Markdown")
|
||||
parser.add_argument(
|
||||
"--devel", action="store_true", help="Create swagger link to development branch"
|
||||
)
|
||||
parser.add_argument(
|
||||
"--output-file", type=str, default=None, help="File to write the OpenAPI Specification to"
|
||||
)
|
||||
|
||||
100
tests/test_doc.py
Normal file
100
tests/test_doc.py
Normal file
@ -0,0 +1,100 @@
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from unittest.mock import patch
|
||||
|
||||
import pytest
|
||||
|
||||
DIR_PROJECT_ROOT = Path(__file__).parent.parent
|
||||
DIR_TESTDATA = Path(__file__).parent / "testdata"
|
||||
|
||||
|
||||
def test_openapi_spec_current(config_eos):
|
||||
"""Verify the openapi spec hasn´t changed."""
|
||||
expected_spec_path = DIR_PROJECT_ROOT / "openapi.json"
|
||||
new_spec_path = DIR_TESTDATA / "openapi-new.json"
|
||||
|
||||
with open(expected_spec_path) as f_expected:
|
||||
expected_spec = json.load(f_expected)
|
||||
|
||||
# Patch get_config and import within guard to patch global variables within the fastapi_server module.
|
||||
with patch("akkudoktoreos.config.config.get_config", return_value=config_eos):
|
||||
# Ensure the script works correctly as part of a package
|
||||
root_dir = Path(__file__).resolve().parent.parent
|
||||
sys.path.insert(0, str(root_dir))
|
||||
from scripts import generate_openapi
|
||||
|
||||
spec = generate_openapi.generate_openapi()
|
||||
|
||||
with open(new_spec_path, "w") as f_new:
|
||||
json.dump(spec, f_new, indent=4, sort_keys=True)
|
||||
|
||||
# Serialize to ensure comparison is consistent
|
||||
spec_str = json.dumps(spec, indent=4, sort_keys=True)
|
||||
expected_spec_str = json.dumps(expected_spec, indent=4, sort_keys=True)
|
||||
|
||||
try:
|
||||
assert spec_str == expected_spec_str
|
||||
except AssertionError as e:
|
||||
pytest.fail(
|
||||
f"Expected {new_spec_path} to equal {expected_spec_path}.\n"
|
||||
+ f"If ok: `make gen-docs` or `cp {new_spec_path} {expected_spec_path}`\n"
|
||||
)
|
||||
|
||||
|
||||
def test_openapi_md_current(config_eos):
|
||||
"""Verify the generated openapi markdown hasn´t changed."""
|
||||
expected_spec_md_path = DIR_PROJECT_ROOT / "docs" / "_generated" / "openapi.md"
|
||||
new_spec_md_path = DIR_TESTDATA / "openapi-new.md"
|
||||
|
||||
with open(expected_spec_md_path) as f_expected:
|
||||
expected_spec_md = f_expected.read()
|
||||
|
||||
# Patch get_config and import within guard to patch global variables within the fastapi_server module.
|
||||
with patch("akkudoktoreos.config.config.get_config", return_value=config_eos):
|
||||
# Ensure the script works correctly as part of a package
|
||||
root_dir = Path(__file__).resolve().parent.parent
|
||||
sys.path.insert(0, str(root_dir))
|
||||
from scripts import generate_openapi_md
|
||||
|
||||
spec_md = generate_openapi_md.generate_openapi_md()
|
||||
|
||||
with open(new_spec_md_path, "w") as f_new:
|
||||
f_new.write(spec_md)
|
||||
|
||||
try:
|
||||
assert spec_md == expected_spec_md
|
||||
except AssertionError as e:
|
||||
pytest.fail(
|
||||
f"Expected {new_spec_md_path} to equal {expected_spec_md_path}.\n"
|
||||
+ f"If ok: `make gen-docs` or `cp {new_spec_md_path} {expected_spec_md_path}`\n"
|
||||
)
|
||||
|
||||
|
||||
def test_config_md_current(config_eos):
|
||||
"""Verify the generated configuration markdown hasn´t changed."""
|
||||
expected_config_md_path = DIR_PROJECT_ROOT / "docs" / "_generated" / "config.md"
|
||||
new_config_md_path = DIR_TESTDATA / "config-new.md"
|
||||
|
||||
with open(expected_config_md_path) as f_expected:
|
||||
expected_config_md = f_expected.read()
|
||||
|
||||
# Patch get_config and import within guard to patch global variables within the fastapi_server module.
|
||||
with patch("akkudoktoreos.config.config.get_config", return_value=config_eos):
|
||||
# Ensure the script works correctly as part of a package
|
||||
root_dir = Path(__file__).resolve().parent.parent
|
||||
sys.path.insert(0, str(root_dir))
|
||||
from scripts import generate_config_md
|
||||
|
||||
config_md = generate_config_md.generate_config_md()
|
||||
|
||||
with open(new_config_md_path, "w") as f_new:
|
||||
f_new.write(config_md)
|
||||
|
||||
try:
|
||||
assert config_md == expected_config_md
|
||||
except AssertionError as e:
|
||||
pytest.fail(
|
||||
f"Expected {new_config_md_path} to equal {expected_config_md_path}.\n"
|
||||
+ f"If ok: `make gen-docs` or `cp {new_config_md_path} {expected_config_md_path}`\n"
|
||||
)
|
||||
@ -1,56 +0,0 @@
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from unittest.mock import patch
|
||||
|
||||
import pytest
|
||||
|
||||
DIR_PROJECT_ROOT = Path(__file__).parent.parent
|
||||
DIR_TESTDATA = Path(__file__).parent / "testdata"
|
||||
|
||||
|
||||
def test_openapi_spec_current(config_eos):
|
||||
"""Verify the openapi spec hasn´t changed."""
|
||||
expected_spec_path = DIR_PROJECT_ROOT / "openapi.json"
|
||||
new_spec_path = DIR_TESTDATA / "openapi-new.json"
|
||||
expected_spec_md_path = DIR_TESTDATA / "openapi.md"
|
||||
new_spec_md_path = DIR_TESTDATA / "openapi-new.md"
|
||||
|
||||
with open(expected_spec_path) as f_expected:
|
||||
expected_spec = json.load(f_expected)
|
||||
with open(expected_spec_md_path) as f_expected:
|
||||
expected_spec_md = f_expected.read()
|
||||
|
||||
# Patch get_config and import within guard to patch global variables within the fastapi_server module.
|
||||
with patch("akkudoktoreos.config.config.get_config", return_value=config_eos):
|
||||
# Ensure the script works correctly as part of a package
|
||||
root_dir = Path(__file__).resolve().parent.parent
|
||||
sys.path.insert(0, str(root_dir))
|
||||
from scripts import generate_openapi, generate_openapi_md
|
||||
|
||||
spec = generate_openapi.generate_openapi()
|
||||
spec_md = generate_openapi_md.generate_openapi_md()
|
||||
|
||||
with open(new_spec_path, "w") as f_new:
|
||||
json.dump(spec, f_new, indent=4, sort_keys=True)
|
||||
with open(new_spec_md_path, "w") as f_new:
|
||||
f_new.write(spec_md)
|
||||
|
||||
# Serialize to ensure comparison is consistent
|
||||
spec_str = json.dumps(spec, indent=4, sort_keys=True)
|
||||
expected_spec_str = json.dumps(expected_spec, indent=4, sort_keys=True)
|
||||
|
||||
try:
|
||||
assert spec_str == expected_spec_str
|
||||
except AssertionError as e:
|
||||
pytest.fail(
|
||||
f"Expected {new_spec_path} to equal {expected_spec_path}.\n"
|
||||
+ f"If ok: cp {new_spec_path} {expected_spec_path}\n"
|
||||
)
|
||||
try:
|
||||
assert spec_md == expected_spec_md
|
||||
except AssertionError as e:
|
||||
pytest.fail(
|
||||
f"Expected {new_spec_md_path} to equal {expected_spec_md_path}.\n"
|
||||
+ f"If ok: cp {new_spec_md_path} {expected_spec_md_path}\n"
|
||||
)
|
||||
Loading…
Reference in New Issue
Block a user