Update vehicle allocation and build docs [makedocs]

docs/dev-guide/components/vehicle_allocation.md

@@ -0,0 +1,47 @@
+(component-vehicle_allocation)=
+# Vehicle Allocation
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.vehicle_allocation.py
+```
+
+The vehicle allocation model selects which vehicle would be used for a tour of given occupancy. The alternatives for the vehicle
+allocation model consist of the vehicles owned by the household and an additional non household vehicle option. (Zero-auto
+households would be assigned the non-household vehicle option since there are no owned vehicles in the household).
+A vehicle is selected for each occupancy level set by the user such that different tour modes that have different occupancies could see different operating
+characteristics. The output of the vehicle allocation model is appended to the tour table with column names [vehicle_occup_{occupancy}](vehicle_occup_{occupancy}) and the values are
+the vehicle type selected.
+
+In [prototype_mtc_extended](prototype_mtc_extended), three occupancy levels are used: 1, 2, and 3.5.  The auto operating cost
+for occupancy level 1 is used in the drive alone mode and drive to transit modes. Occupancy levels 2 and 3.5 are used for shared
+ride 2 and shared ride 3+ auto operating costs, respectively.  Auto operating costs are selected in the mode choice pre-processors by selecting the allocated
+vehicle type data from the vehicles table. If the allocated vehicle type was the non-household vehicle, the auto operating costs uses
+the previous default value from [prototype_mtc](prototype_mtc). All trips and atwork subtours use the auto operating cost of the parent tour.  Functionality
+was added in tour and atwork subtour mode choice to annotate the tour table and create a ``selected_vehicle`` which denotes the actual vehicle used.
+If the tour mode does not include a vehicle, then the ``selected_vehicle`` entry is left blank.
+
+The current implementation does not account for possible use of the household vehicles by other household members.  Thus, it is possible for a
+selected vehicle to be used in two separate tours at the same time.
+
+## Structure
+
+- *Configuration File*: `vehicle_allocation.yaml`
+- *Result Field*: `vehicle_occup_{occupancy}`
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: VehicleAllocationSettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MTC Extended](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc_extended/configs/vehicle_type_choice.yaml)
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: vehicle_allocation
+```