docs: fix warnings from sphinx build (#286)

powersimdata/data_access/csv_store.py

@@ -21,6 +21,7 @@ def __init__(self, ssh_client):
     def get_table(self, filename, path_on_server):
         """Read the given file from the server, falling back to local copy if
         unable to connect.
+
         :return: (*pandas.DataFrame*) -- the specified table as a data frame.
         """
         local_path = Path(server_setup.LOCAL_DIR, filename)
@@ -39,6 +40,7 @@ def get_table(self, filename, path_on_server):
 
     def _get_from_server(self, path_on_server):
         """Return csv table from server.
+
         :return: (*pandas.DataFrame*) -- the specified file as a data frame.
         """
         with self.ssh_client.open_sftp() as sftp:
@@ -47,6 +49,7 @@ def _get_from_server(self, path_on_server):
 
     def _parse_csv(self, file_object):
         """Read file from disk into data frame
+
         :param str, path object or file-like object file_object: a reference to
         the csv file
         :return: (*pandas.DataFrame*) -- the specified file as a data frame.

powersimdata/data_access/execute_list.py

@@ -11,6 +11,7 @@ class ExecuteTable(SqlStore):
 
     def get_status(self, scenario_id):
         """Get status of scenario by scenario_id
+
         :param str scenario_id: the scenario id
         :return: (*pandas.DataFrame*) -- results as a data frame.
         """
@@ -21,6 +22,7 @@ def get_status(self, scenario_id):
 
     def get_execute_table(self, limit=None):
         """Return the execute table as a data frame
+
         :return: (*pandas.DataFrame*) -- execute list as a data frame.
         """
         query = self.select_all()
@@ -33,6 +35,7 @@ def get_execute_table(self, limit=None):
 
     def add_entry(self, scenario_info):
         """Add entry to execute list
+
         :param collections.OrderedDict scenario_info: entry to add
         """
         scenario_id, status = scenario_info["id"], "created"
@@ -78,6 +81,7 @@ def __init__(self, ssh_client):
     def get_execute_table(self):
         """Returns execute table from server if possible, otherwise read local
         copy. Updates the local copy upon successful server connection.
+
         :return: (*pandas.DataFrame*) -- execute list as a data frame.
         """
         return self.get_table("ExecuteList.csv", server_setup.EXECUTE_LIST)

powersimdata/data_access/scenario_list.py

@@ -30,6 +30,7 @@ class ScenarioTable(SqlStore):
 
     def get_scenario_by_id(self, scenario_id):
         """Get entry from scenario list by id
+
         :param str scenario_id: scenario id
         :return: (*pandas.DataFrame*) -- results as a data frame.
         """

powersimdata/data_access/sql_store.py

@@ -28,6 +28,7 @@ def execute(self, sql, args=None):
 
 def get_connection():
     """Temporary connection used for local development
+
     :return: (*str*) -- connection string for postgres db
     """
     return "dbname=psd host=localhost user=postgres password=example"
@@ -36,6 +37,7 @@ def get_connection():
 def get_cursor_factory():
     """Return cursor class to be passed to connection for executing sql.
     Default to DictCursor unless DEBUG_MODE is set.
+
     :returns: a cursor class callable for use by psycopg2 connection
     :rtype: psycopg2.extras.DictCursor or powersimdata.data_access.sql_store.LoggingCursor
     """
@@ -46,6 +48,7 @@ def get_cursor_factory():
 
 def to_data_frame(result):
     """Convert psycopg2 result set to data frame
+
     :param list result: list of DictRow containing query results cast to strings
     :return: (*pd.DataFrame*) -- query results as data frame
     """
@@ -67,6 +70,7 @@ def __init__(self):
 
     def _table(self):
         """Get table object for use in query generation.
+
         :return: (*psycopg2.sql.Identifier*) -- Identifier instance
         :raises ValueError: if :attr:`table` has not been defined.
         """
@@ -76,6 +80,7 @@ def _table(self):
 
     def _columns(self, subset=None):
         """Get column list object for use in query generation.
+
         :return: (*psycopg2.sql.SQL*) -- SQL instance
         :raises ValueError: if :attr:`columns` has not been defined.
         """
@@ -89,25 +94,28 @@ def _columns(self, subset=None):
 
     def select_all(self):
         """Build SELECT query.
-        :return (*psycopg2.sql.SQL*) -- query representation
+
+        :return: (*psycopg2.sql.SQL*) -- query representation
         """
         return SQL("SELECT {fields} FROM {table}").format(
             fields=self._columns(), table=self._table()
         )
 
     def select_where(self, key):
         """Build SELECT .. WHERE query filtered by key
+
         :param str key: column to use in WHERE clause
-        :return (*psycopg2.sql.SQL*) -- query representation
+        :return: (*psycopg2.sql.SQL*) -- query representation
         """
         where_clause = SQL(" WHERE {key} = %s").format(key=Identifier(key))
         return self.select_all() + where_clause
 
     def insert(self, subset=None):
         """Build INSERT statement on current table for all columns, or subset if
         specified.
+
         :param iterable subset: collection of columns to specify in query
-        :return (*psycopg2.sql.SQL*) -- template for insert statement
+        :return: (*psycopg2.sql.SQL*) -- template for insert statement
         """
         n_values = len(subset) if subset is not None else len(self.columns)
         return SQL("INSERT INTO {table} ({fields}) VALUES ({values})").format(
@@ -118,15 +126,17 @@ def insert(self, subset=None):
 
     def delete(self, key):
         """Build DELETE .. WHERE statement on current table using key to filter.
+
         :param str key: column to use in WHERE clause
-        :return (*psycopg2.sql.SQL*) -- template for delete statement
+        :return: (*psycopg2.sql.SQL*) -- template for delete statement
         """
         return SQL("DELETE FROM {table} WHERE {key} = %s").format(
             table=self._table(), key=Identifier(key)
         )
 
     def __enter__(self):
         """Context manager entrypoint.
+
         :return: the current instance
         """
         self.conn.__enter__()
@@ -137,6 +147,7 @@ def __enter__(self):
     def __exit__(self, exc_type, exc_value, traceback):
         """Context manager teardown. Either commit or rollback transaction and
         close the connection. Reraise exception if applicable.
+
         :raises SqlException: If any exception occurred. Sets the original
         exception as the cause of the new one.
         """

powersimdata/design/clean_capacity_scaling.py

@@ -138,6 +138,7 @@ def _make_zonename2target(grid, targets):
 
 def _get_scenario_length(scenario):
     """Get the number of hours in a scenario.
+
     :param powersimdata.scenario.scenario.Scenario scenario: A Scenario instance.
     :return: (*int*) -- the number of hours in the scenario.
     """
@@ -157,6 +158,7 @@ def add_resource_data_to_targets(input_targets, scenario, calculate_curtailment=
     """Add resource data to targets. This data includes: previous capacity,
     previous generation, previous capacity factor (with and without curtailment),
     and previous curtailment.
+
     :param pandas.DataFrame input_targets: table includeing target names, used to
         summarize resource data.
     :param powersimdata.scenario.scenario.Scenario scenario: A Scenario instance.
@@ -227,6 +229,7 @@ def add_resource_data_to_targets(input_targets, scenario, calculate_curtailment=
 
 def add_demand_to_targets(input_targets, scenario):
     """Add demand data to targets.
+
     :param pandas.DataFrame input_targets: table including target names, used to
         summarize demand.
     :param powersimdata.scenario.scenario.Scenario scenario: A Scenario instance.
@@ -245,6 +248,7 @@ def add_demand_to_targets(input_targets, scenario):
 
 def add_shortfall_to_targets(input_targets):
     """Add shortfall data to targets.
+
     :param pandas.DataFrame input_targets: table with demand, prev_generation,
         and ce_target_fraction.
     :return: (*pandas.DataFrame*) -- DataFrame of targets including shortfall data.
@@ -275,6 +279,7 @@ def add_shortfall_to_targets(input_targets):
 
 def calculate_overall_shortfall(targets, method, normalized=False):
     """Calculates overall shortfall.
+
     :param pandas.DataFrame targets: table of targets.
     :param str method: shortfall calculation method ("independent" or "collaborative").
     :param bool normalized: whether to normalize by total demand.
@@ -309,6 +314,7 @@ def add_new_capacities_independent(
     input_targets, scenario_length, addl_curtailment=None
 ):
     """Calculates new capacities based on an Independent strategy.
+
     :param pandas.DataFrame input_targets: table of targets.
     :param int scenario_length: number of hours in new scenario.
     :param pandas.DataFrame/None addl_curtailment: additional expected curtailment
@@ -372,6 +378,7 @@ def add_new_capacities_collaborative(
     input_targets, scenario_length, solar_fraction=None, addl_curtailment=None
 ):
     """Calculates new capacities based on a Collaborative strategy.
+
     :param pandas.DataFrame input_targets: table of targets.
     :param int scenario_length: number of hours in new scenario.
     :param float/None solar_fraction: how much new capacity should be solar.
@@ -488,6 +495,7 @@ def calculate_clean_capacity_scaling(
     """Given a reference scenario (to get 'baseline' values), a method, and a set
     of targets (either via a dataframe or a filename to load a dataframe),
     calculate capacities for a new scenario to meet the calculated shortfall.
+
     :param powersimdata.scenario.scenario.Scenario ref_scenario: Scenario instance
         to get baseline capacities and capacity factors from.
     :param str method: which capacity scaling method to use.

powersimdata/input/change_table.py

@@ -78,7 +78,7 @@ class ChangeTable(object):
         keys in the dictionary are: *'capacity'*, *'from_bus_id'* and
         *'to_bus_id'* with values giving the capacity of the line and
         the bus id at each end of the line.
-    * *'new_plant':
+    * *'new_plant'*:
         value is a list. Each entry in this list is a dictionary enclosing
         all the information needed to add a new generator to the grid. The
         keys in the dictionary are *'type'*, *'bus_id'*, *'Pmax'* for
@@ -341,6 +341,7 @@ def scale_renewable_stubs(self, **kwargs):
 
     def scale_congested_mesh_branches(self, ref_scenario, **kwargs):
         """Scales congested branches based on previous scenario results.
+
         :param powersimdata.scenario.scenario.Scenario ref_scenario: the
             reference scenario to be used in determining branch scaling.
 

powersimdata/scenario/state.py

@@ -5,6 +5,7 @@
 class State(object):
     """Defines an interface for encapsulating the behavior associated with a
         particular state of the Scenario object.
+
     :param powrsimdata.scenario.scenario.Scenario scenario: scenario instance
     :raise TypeError: if not instantiated through a derived class
     """