Usage doc (#679)

* Added usage doc to controllers

* Adding usage doc to params.py

* Finish usage doc

* pep8 and cleanup

* Remove usage examples from params.py

flow/controllers/base_controller.py

@@ -11,6 +11,16 @@ class BaseController:
     safe_action to ensure that controls are never made that could
     cause the system to crash.
 
+    Usage
+    -----
+    >>> from flow.core.params import VehicleParams
+    >>> from flow.controllers import IDMController
+    >>> vehicles = VehicleParams()
+    >>> vehicles.add("human", acceleration_controller=(IDMController, {}))
+
+    Note: You can replace "IDMController" with any subclass controller of your
+    choice.
+
     Parameters
     ----------
     veh_id : str

flow/controllers/base_lane_changing_controller.py

@@ -7,10 +7,21 @@ class BaseLaneChangeController:
     Instantiates a controller and forces the user to pass a
     lane_changing duration to the controller.
 
+    Usage
+    -----
+    >>> from flow.core.params import VehicleParams
+    >>> from flow.controllers import SimLaneChangeController
+    >>> vehicles = VehicleParams()
+    >>> vehicles.add("human",
+    >>>              lane_change_controller=(SimLaneChangeController, {}))
+
+    Note: You can replace SimLaneChangeController with any lane changing
+    controller of your choice.
+
     Parameters
     ----------
     veh_id : str
-        ID of the vehi cle this controller is used for
+        ID of the vehicle this controller is used for
     lane_change_params : dict
         Dictionary of lane changes params that may optional contain
         "min_gap", which denotes the minimize safe gap (in meters) a car

flow/controllers/base_routing_controller.py

@@ -7,6 +7,16 @@ class BaseRouter:
     These controllers are used to dynamically change the routes of vehicles
     after initialization.
 
+    Usage
+    -----
+    >>> from flow.core.params import VehicleParams
+    >>> from flow.controllers import ContinuousRouter
+    >>> vehicles = VehicleParams()
+    >>> vehicles.add("human", routing_controller=(ContinuousRouter, {}))
+
+    Note: You can replace "ContinuousRouter" with any routing controller you
+    want.
+
     Parameters
     ----------
     veh_id : str

flow/controllers/car_following_models.py

@@ -17,6 +17,10 @@
 class CFMController(BaseController):
     """CFM controller.
 
+    Usage
+    -----
+    See BaseController for usage example.
+
     Attributes
     ----------
     veh_id : str
@@ -89,6 +93,10 @@ class BCMController(BaseController):
 
     This model looks ahead and behind when computing its acceleration.
 
+    Usage
+    -----
+    See BaseController for usage example.
+
     Attributes
     ----------
     veh_id : str
@@ -240,6 +248,10 @@ def get_accel(self, env):
 class OVMController(BaseController):
     """Optimal Vehicle Model controller.
 
+    Usage
+    -----
+    See BaseController for usage example.
+
     Attributes
     ----------
     veh_id : str
@@ -319,6 +331,10 @@ def get_accel(self, env):
 class LinearOVM(BaseController):
     """Linear OVM controller.
 
+    Usage
+    -----
+    See BaseController for usage example.
+
     Attributes
     ----------
     veh_id : str
@@ -389,6 +405,10 @@ class IDMController(BaseController):
     states in empirical observations and microscopic simulations." Physical
     review E 62.2 (2000): 1805.
 
+    Usage
+    -----
+    See BaseController for usage example.
+
     Attributes
     ----------
     veh_id : str
@@ -472,6 +492,8 @@ class SimCarFollowingController(BaseController):
     Note that methods for implementing noise and failsafes through
     BaseController, are not available here. However, similar methods are
     available through sumo when initializing the parameters of the vehicle.
+
+    Usage: See BaseController for usage example.
     """
 
     def get_accel(self, env):

flow/controllers/lane_change_controllers.py

@@ -5,15 +5,21 @@
 
 
 class SimLaneChangeController(BaseLaneChangeController):
-    """A controller used to enforce sumo lane-change dynamics on a vehicle."""
+    """A controller used to enforce sumo lane-change dynamics on a vehicle.
+
+    Usage: See base class for usage example.
+    """
 
     def get_lane_change_action(self, env):
         """See parent class."""
         return None
 
 
 class StaticLaneChanger(BaseLaneChangeController):
-    """A lane-changing model used to keep a vehicle in the same lane."""
+    """A lane-changing model used to keep a vehicle in the same lane.
+
+    Usage: See base class for usage example.
+    """
 
     def get_lane_change_action(self, env):
         """See parent class."""

flow/controllers/rlcontroller.py

@@ -9,6 +9,8 @@ class RLController(BaseController):
     Vehicles with this class specified will be stored in the list of the RL IDs
     in the Vehicles class.
 
+    Usage: See base class for usage example.
+
     Attributes
     ----------
     veh_id : str

flow/controllers/routing_controllers.py

@@ -11,6 +11,10 @@ class ContinuousRouter(BaseRouter):
 
     This class is useful if vehicles are expected to continuously follow the
     same route, and repeat said route once it reaches its end.
+
+    Usage
+    -----
+    See base class for usage example.
     """
 
     def choose_route(self, env):
@@ -43,6 +47,10 @@ class MinicityRouter(BaseRouter):
     """A router used to continuously re-route vehicles in minicity scenario.
 
     This class allows the vehicle to pick a random route at junctions.
+
+    Usage
+    -----
+    See base class for usage example.
     """
 
     def choose_route(self, env):
@@ -75,7 +83,12 @@ def choose_route(self, env):
 
 
 class GridRouter(BaseRouter):
-    """A router used to re-route a vehicle within a grid environment."""
+    """A router used to re-route a vehicle within a grid environment.
+
+    Usage
+    -----
+    See base class for usage example.
+    """
 
     def choose_route(self, env):
         """See parent class."""
@@ -94,6 +107,10 @@ class BayBridgeRouter(ContinuousRouter):
     """Assists in choosing routes in select cases for the Bay Bridge scenario.
 
     Extension to the Continuous Router.
+
+    Usage
+    -----
+    See base class for usage example.
     """
 
     def choose_route(self, env):

flow/controllers/velocity_controllers.py

@@ -10,6 +10,10 @@ class FollowerStopper(BaseController):
     Dissipation of stop-and-go waves via control of autonomous vehicles:
     Field experiments https://arxiv.org/abs/1705.01693
 
+    Usage
+    -----
+    See base class for example.
+
     Parameters
     ----------
     veh_id : str
@@ -118,6 +122,10 @@ class PISaturation(BaseController):
     Dissipation of stop-and-go waves via control of autonomous vehicles:
     Field experiments https://arxiv.org/abs/1705.01693
 
+    Usage
+    -----
+    See base class for example.
+
     Parameters
     ----------
     veh_id : str

flow/core/params.py

@@ -37,7 +37,7 @@ class TrafficLightParams:
     def __init__(self, baseline=False):
         """Instantiate base traffic light.
 
-        Parameters
+        Attributes
         ----------
         baseline: bool
         """
@@ -354,7 +354,7 @@ class SimParams(object):
 
     All subsequent parameters of the same type must extend this.
 
-    Parameters
+    Attributes
     ----------
     sim_step : float optional
         seconds per simulation step; 0.1 by default
@@ -415,7 +415,7 @@ class AimsunParams(SimParams):
 
     Extends SimParams.
 
-    Parameters
+    Attributes
     ----------
     sim_step : float optional
         seconds per simulation step; 0.1 by default
@@ -505,7 +505,7 @@ class SumoParams(SimParams):
     specifying whether to use sumo's gui during a run, and other features
     described in the Attributes below.
 
-    Parameters
+    Attributes
     ----------
     port : int, optional
         Port for Traci to connect to; finds an empty port by default
@@ -596,7 +596,7 @@ class EnvParams:
     coefficients to the reward function, as well as specifying how the
     positions of vehicles are modified in between rollouts.
 
-    Parameters
+    Attributes
     ----------
     additional_params : dict, optional
         Specify additional environment params for a specific
@@ -655,7 +655,7 @@ class NetParams:
     for a specific scenario, refer to the ADDITIONAL_NET_PARAMS variable
     located in the scenario file.
 
-    Parameters
+    Attributes
     ----------
     inflows : InFlows type, optional
         specifies the inflows of specific edges and the types of vehicles
@@ -693,7 +693,7 @@ class InitialConfig:
     network at the start of a rollout. By default, vehicles are uniformly
     distributed in the network.
 
-    Parameters
+    Attributes
     ----------
     shuffle : bool, optional  # TODO: remove
         specifies whether the ordering of vehicles in the Vehicles class
@@ -760,7 +760,7 @@ def __init__(self,
 class SumoCarFollowingParams:
     """Parameters for sumo-controlled acceleration behavior.
 
-    Parameters
+    Attributes
     ----------
     speed_mode : str or int, optional
         may be one of the following:
@@ -879,7 +879,7 @@ def __init__(
 class SumoLaneChangeParams:
     """Parameters for sumo-controlled lane change behavior.
 
-    Parameters
+    Attributes
     ----------
     lane_change_mode : str or int, optional
         may be one of the following: