Write documentation for sequence API module

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

@@ -16,19 +16,54 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
-import ifcopenshell.util.date
-
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, task=None, is_recurring=False):
+        """Adds a task time to a task
+
+        Some tasks, such as activities within a work breakdown structure or
+        overall maintenance tasks will have time related information. This
+        includes start dates, durations, end dates, and possible recurring times
+        (especially for maintenance tasks).
+
+        :param task: The task to add time data to.
+        :type task: ifcopenshell.entity_instance.entity_instance
+        :param is_recurring: Whether or not the time should recur.
+        :type is_recurring: bool
+        :return: The newly created IfcTaskTime.
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            # Let's imagine we are creating a construction schedule.
+            schedule = ifcopenshell.api.run("sequence.add_work_schedule", model, name="Construction Schedule A")
+
+            # Create a portion of a work breakdown structure.
+            construction = ifcopenshell.api.run("sequence.add_task", model,
+                work_schedule=schedule, name="Construction", identification="C")
+            superstructure = ifcopenshell.api.run("sequence.add_task", model,
+                parent_task=construction, name="Superstructure", identification="C3")
+            task = ifcopenshell.api.run("sequence.add_task", model,
+                parent_task=superstructure, name="Ground Floor FRP", identification="C3.1")
+
+            # Add time data. Note that time data is blank by default.
+            time = ifcopenshell.api.run("sequence.add_task_time", model, task=task)
+
+            # Let's say our task starts on the first of January when everybody
+            # is still drunk from the new years celebration, and lasts for 2
+            # days. Note we don't need to specify the end date, as that is
+            # derived from the start plus the duration. In this simple example,
+            # no calendar has been specified, so we are working 24/7. Yikes!
+            ifcopenshell.api.run("sequence.edit_task_time", model,
+                task_time=time, attributes={"ScheduleStart": "2000-01-01", "ScheduleDuration": "P2D"})
+        """
         self.file = file
-        self.settings = {
-            "task": None,
-        }
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"task": task, "is_recurring": is_recurring}
 
     def execute(self):
-        task_time = self.file.create_entity("IfcTaskTime")
+        if self.settings["is_recurring"]:
+            task_time = self.file.create_entity("IfcTaskTime")
+        else:
+            task_time = self.file.create_entity("IfcTaskTimeRecurring")
         self.settings["task"].TaskTime = task_time
         return task_time