Write documentation for sequence API module

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

@@ -21,14 +21,92 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, relating_process=None, related_process=None, sequence_type="FINISH_START"):
+        """Assign a sequential relationship between tasks
+
+        Tasks in construction sequencing typically have sequence relationships
+        between them, indicating that one task must happen after another. This
+        is used to automatically compute new start and end dates and cascade
+        changes when dates are changed. This is also used to calculate critical
+        paths and floats.
+
+        There are four types of sequence relationships, known as finish to
+        start, finish to finish, start to start, and start to finish, sometimes
+        abbreviated as a (FS, FF, SS, and SF). The most common is the finish to
+        start relationship, indicating that the previous task must finish before
+        the next task can start.
+
+        You must not create cyclical task sequences. This makes the computer
+        unhappy.
+
+        Note that "previous" or "next" does not necessarily mean the task
+        chronologically happens before or after. They simply indicate the order
+        of the sequence relationship. For this reason, they are often called
+        predecessor and successor tasks in the planning profession.
+
+        :param relating_process: The previous / predecessor task.
+        :type relating_process: ifcopenshell.entity_instance.entity_instance
+        :param related_process: The next / successor task.
+        :type related_process: ifcopenshell.entity_instance.entity_instance
+        :param sequence_type: Choose from FINISH_START, FINISH_FINISH,
+            START_START, or START_FINISH.
+        :return: The newly created IfcRelSequence
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            # 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 imagine a root construction task
+            construction = ifcopenshell.api.run("sequence.add_task", model,
+                work_schedule=schedule, name="Construction", identification="C")
+
+            # Let's imagine we're doing a typically formwork, reinforcement,
+            # pour sequence. Let's start with the formwork. It'll take us 2
+            # days.
+            formwork = ifcopenshell.api.run("sequence.add_task", model,
+                parent_task=construction, name="Formwork", identification="C.1")
+            time = ifcopenshell.api.run("sequence.add_task_time", model, task=formwork)
+            ifcopenshell.api.run("sequence.edit_task_time", model,
+                task_time=time, attributes={"ScheduleStart": "2000-01-01", "ScheduleDuration": "P2D"})
+
+            # Now let's do the reinforcement. It'll take us another 2 days.
+            reinforcement = ifcopenshell.api.run("sequence.add_task", model,
+                parent_task=construction, name="Reinforcement", identification="C.2")
+            time = ifcopenshell.api.run("sequence.add_task_time", model, task=reinforcement)
+            ifcopenshell.api.run("sequence.edit_task_time", model,
+                task_time=time, attributes={"ScheduleStart": "2000-01-01", "ScheduleDuration": "P2D"})
+
+            # Now the pour itself. It'll only take 1 day.
+            pour = ifcopenshell.api.run("sequence.add_task", model,
+                parent_task=construction, name="Reinforcement", identification="C.3")
+            time = ifcopenshell.api.run("sequence.add_task_time", model, task=pour)
+            ifcopenshell.api.run("sequence.edit_task_time", model,
+                task_time=time, attributes={"ScheduleStart": "2000-01-01", "ScheduleDuration": "P1D"})
+
+            # Now let's say the formwork must finish before the reinforcement
+            # can start, and the reinforcement must finish before the pour can
+            # start. This is a typical finish to start relationship (FS).
+            ifcopenshell.api.run("sequence.assign_sequence", model,
+                relating_process=formwork, related_process=reinforcement)
+            ifcopenshell.api.run("sequence.assign_sequence", model,
+                relating_process=reinforcement, related_process=pour)
+
+            # Notice how we set all the scheduled start dates arbitrarily at
+            # 2000-01-01. This is because we can ask IfcOpenShell to
+            # automatically cascade the dates, starting from any task. This will
+            # update the reinforcement date to be 2000-01-03 and the pour date
+            # to be 2000-01-05.
+            ifcopenshell.api.run("sequence.cascade_schedule", model, task=formwork)
+        """
         self.file = file
         self.settings = {
-            "relating_process": None,
-            "related_process": None,
+            "relating_process": relating_process,
+            "related_process": related_process,
+            "sequence_type": sequence_type,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         for rel in self.settings["related_process"].IsSuccessorFrom or []:
@@ -38,11 +116,9 @@ class Usecase:
             "IfcRelSequence",
             **{
                 "GlobalId": ifcopenshell.guid.new(),
-                "OwnerHistory": ifcopenshell.api.run(
-                    "owner.create_owner_history", self.file
-                ),
+                "OwnerHistory": ifcopenshell.api.run("owner.create_owner_history", self.file),
                 "RelatingProcess": self.settings["relating_process"],
                 "RelatedProcess": self.settings["related_process"],
-                "SequenceType": "FINISH_START",
+                "SequenceType": self.settings["sequence_type"],
             }
         )