Write documentation for sequence API module

src/ifcopenshell-python/ifcopenshell/api/sequence/calculate_task_duration.py

@@ -23,11 +23,64 @@ import ifcopenshell.util.element
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, task=None):
+        """Calculates the task duration based on resource usage
+
+        If a task has labour or equipment resources assigned to it, its duration
+        may be parametrically derived from the scheduled work of the resource.
+        For example, a labour resource with scheduled work of 10 working days
+        and a resource utilisation of 200% (i.e. two labour teams) will imply
+        that the task duration is 5 working days.
+
+        If this data is not available, such as if the task has no resources,
+        then nothing happens.
+
+        :param task: The IfcTask to calculate the duration for.
+        :type task: ifcopenshell.entity_instance.entity_instance
+        :return: None
+        :rtype: None
+
+        Example::
+
+            # Add our own crew
+            crew = ifcopenshell.api.run("resource.add_resource", model, ifc_class="IfcCrewResource")
+
+            # Add some labour to our crew.
+            labour = ifcopenshell.api.run("resource.add_resource", model,
+                parent_resource=crew, ifc_class="IfcLaborResource")
+
+            # Labour resource is quantified in terms of time.
+            quantity = ifcopenshell.api.run("resource.add_resource_quantity", model,
+                resource=labour, ifc_class="IfcQuantityTime")
+
+            # Store the unit time used in hours
+            ifcopenshell.api.run("resource.edit_resource_quantity", model,
+                physical_quantity=quantity, attributes={"TimeValue": 8.0})
+
+            # Let's imagine we've used the resource for 10 days with a
+            # utilisation of 200%.
+            time = ifcopenshell.api.run("resource.add_resource_time", model, resource=labour)
+            ifcopenshell.api.run("resource.edit_resource_time", model,
+                resource_time=time, attributes={"ScheduleWork": "PT80H", "ScheduleUsage": 2})
+
+            # Let's imagine we are creating a construction schedule. All tasks
+            # need to be part of a work schedule.
+            schedule = ifcopenshell.api.run("sequence.add_work_schedule", model, name="Construction Schedule A")
+
+            # Let's create a construction task. Note that the predefined type is
+            # important to distinguish types of tasks.
+            task = ifcopenshell.api.run("sequence.add_task", model,
+                work_schedule=schedule, name="Foundations", identification="A")
+
+            # Assign our resource to the task.
+            ifcopenshell.api.run("sequence.assign_process", model, relating_process=task, related_object=labour)
+
+            # Now we can calculate the task duration based on the resource. This
+            # will set task.TaskTime.ScheduleDuration to be P5D.
+            ifcopenshell.api.run("sequence.calculate_task_duration", model, task=task)
+        """
         self.file = file
-        self.settings = {"task": None}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"task": task}
 
     def execute(self):
         self.seconds_per_workday = self.calculate_seconds_per_workday()