fixed inconsistent docstrings

dos-group · Nov 6, 2023 · d4ccd7c · d4ccd7c
1 parent 0b30f85
commit d4ccd7c
Show file tree

Hide file tree

Showing 6 changed files with 41 additions and 31 deletions.
diff --git a/vessim/__init__.py b/vessim/__init__.py
@@ -19,17 +19,22 @@ class TimeSeriesApi:
             actual data between timestamps is computed using either `ffill` or `bfill`.
             If you wish a different behavior, you have to change your actual data
             beforehand (e.g. by resampling into a different frequency).
-        forecast: An optional time-series dataset representing forecasted values.
-            The data should contain two datetime-like indices. One is the
+
+        forecast: An optional time-series dataset representing forecasted values. The
+            data should contain two datetime-like indices. One is the
             `Request Timestamp`, marking the time when the forecast was made. One is the
             `Forecast Timestamp`, indicating the time the forecast is made for.
+
             - If data does not include a `Request Timestamp`, it is treated as a static
-                forecast that does not change over time.
-            - If `forecast` is not provided, predictions are derived from the actual data
-                when requesting forecasts (actual data is treated as static forecast).
+              forecast that does not change over time.
+
+            - If `forecast` is not provided, predictions are derived from the actual
+              data when requesting forecasts (actual data is treated as static forecast).
+
             - When using a non-static forecast, you have to be aware that all the
-                zones/column names also have to appear in the actual dataframe because
-                some actual values are used for interpolation.
+              zones/column names also have to appear in the actual dataframe because some
+              actual values are used for interpolation.
+
         fill_method: Either `ffill` or `bfill`. Determines how actual data is acquired in
             between timestamps. Some data providers like `Solcast` index their data with a
             timestamp marking the end of the time-period that the data is valid for.
@@ -109,7 +114,7 @@ def actual(self, dt: DatetimeLike, zone: Optional[str] = None) -> Any:
 
         Args:
             dt: Timestamp, at which the data is needed.
-            zone: Optional Zone for the data. Has to be provided if there is more than one
+            zone: Optional zone for the data. Has to be provided if there is more than one
                 zone specified in the data. Defaults to None.
 
         Raises:
@@ -136,10 +141,10 @@ def forecast(
         - If no forecast time-series data is provided, actual data is used.
         - Specified timestamps are always rounded down to the nearest existing.
         - If frequency is not specified, all existing data in the window will be returned.
-        - For various resampling methods, the actual value valid at start_time is used.
-            So you have to make sure that there is a valid actual value.
+        - For various resampling methods, the actual value valid at `start_time` is used.
+          So you have to make sure that there is a valid actual value.
         - If there is more than one zone present in the data, zone has to be specified.
-            (Note that zone name must also appear in actual data for non-static forecast.)
+          (Note that zone name must also appear in actual data for non-static forecast.)
         - The forecast does not include the value at `start_time` (see example).
 
         Args:
@@ -149,15 +154,17 @@ def forecast(
             frequency: Optional interval, in which the forecast data is to be provided.
                 Defaults to None.
             resample_method: Optional method, to deal with holes in resampled data.
-                Can be either 'bfill', 'ffill' or an interpolation method.
-                https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.interpolate.html#pandas.DataFrame.interpolate)
+                Can be either `bfill`, `ffill` or an interpolation method.
+                For more information on interpolation methods, see the
+                `pandas documentation <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.interpolate.html>`_.
 
         Returns:
             pd.Series of forecasted data with timestamps of forecast as index.
 
         Raises:
-            ValueError: If there is no available data at apecified zone or time, or
-                there is not enough data for frequency, without resample_method specified.
+            ValueError: If no data is available for the specified zone or time, or if
+                insufficient data exists for the frequency, without `resample_method`
+                specified.
 
         Example:
             >>> index = pd.date_range(

diff --git a/vessim/analysis.py b/vessim/analysis.py
@@ -5,11 +5,11 @@
 
 
 def plot_basic_evaluation(data: pd.DataFrame, title: str = "Evaluation"):
-    """Simple function for plotting of the simulation _data.
+    """Simple function for plotting of the simulation data.
 
     Args:
         data: The dataframe containing the simulation data.
-        title: The title of the plot. Defaults to `Evaluation`
+        title: The title of the plot. Defaults to `Evaluation`.
     """
     data.index = pd.to_datetime(data.index)
 
@@ -100,7 +100,8 @@ def plot_accumulated_emissions(
 ) -> float:
     """Create plot of total carbon emission over time.
 
-    Returns: The total emission over the whole simulation as float.
+    Returns:
+        The total emission over the whole simulation as float.
     """
     emissions = (-p_grid) * carbon_intensity  # 60 Ws * gCO2/kWh
     emissions /= 60000

diff --git a/vessim/core/storage.py b/vessim/core/storage.py
@@ -29,10 +29,11 @@ class SimpleBattery(Storage):
     """(Way too) simple battery.
 
     Args:
-        capacity: Battery capacity in Ws
-        charge_level: Initial charge level in Ws
-        min_soc: Minimum allowed soc for the battery
-        c_rate: C-rate (https://www.batterydesign.net/electrical/c-rate/)
+        capacity: Battery capacity in watt-seconds (Ws).
+        charge_level: Initial charge level in watt-seconds (Ws).
+        min_soc: Minimum allowed state of charge (SoC) for the battery.
+        c_rate: C-rate, which defines the charge and discharge rate of the battery.
+            For more information on C-rate, see `C-rate explanation <https://www.batterydesign.net/electrical/c-rate/>`_.
     """
 
     def __init__(

diff --git a/vessim/sil/api_server.py b/vessim/sil/api_server.py
@@ -19,7 +19,7 @@ class SilApi(ABC):
     necessary cleanup tasks of the child process running the API.
 
     Attributes:
-        app: The FastApi instance to be runned.
+        app: The FastApi instance to be run.
     """
 
     def __init__(self) -> None:
@@ -39,8 +39,10 @@ class ApiServer(multiprocessing.Process):
 
     Args:
         api_type: The type of the class containing the app to be executed.
-        host: The host address, defaults to '127.0.0.1'.
-        port: The port to run the FastAPI application, defaults to 8000.
+        host: The host address where the server will be accessible.
+            Defaults to '127.0.0.1'.
+        port: The port number on which the FastAPI application will run.
+            Defaults to 8000.
     """
 
     def __init__(
@@ -84,11 +86,10 @@ class VessimApi(SilApi):
     """Specialized Vessim API to be executed in a different process.
 
     Initializes a FastAPI instance with specific routes related to the Vessim API.
-    This app is very specific for the use case of the vessim vision paper:
-    https://arxiv.org/pdf/2306.09774.pdf
+    This app is very specific for the use case of the `Vessim vision paper <https://arxiv.org/pdf/2306.09774.pdf>`_.
 
     Attributes:
-        app: The FastApi instance to be runned.
+        app: The FastApi instance to be run.
     """
 
     def __init__(self) -> None:

diff --git a/vessim/sil/http_client.py b/vessim/sil/http_client.py
@@ -22,7 +22,7 @@ def get(self, route: str) -> dict:
             route: The path of the endpoint to send the request to.
 
         Raises:
-            HTTPError if response code is != 200.
+            HTTPError: If response code is != 200.
 
         Returns:
             A dictionary containing the response.
@@ -41,7 +41,7 @@ def put(self, route: str, data: Dict[str, Any] = {}) -> None:
             data: The data to be updated, in dictionary format.
 
         Raises:
-            HTTPError if response code is != 200.
+            HTTPError: If response code is != 200.
         """
         headers = {"Content-type": "application/json"}
         response = requests.put(

diff --git a/vessim/sil/node.py b/vessim/sil/node.py
@@ -10,7 +10,7 @@ class Node:
         id: A unique ID assigned to each node.
         address: The network address of the node.
         port: The application port of the node api.
-        power_mode: The power mode of the node. Default is "high performance".
+        power_mode: The power mode of the node. Default is `high performance`.
     """
 
     existing_ids: Set[str] = set()