Write documentation for sequence API module

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

@@ -18,11 +18,91 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, parent=None, recurrence_type="WEEKLY"):
+        """Define a time to recur at a particular interval
+
+        There are two scenarios where you might want to define a recurring time
+        pattern.
+
+        You might want a task to be scheduled at a recurring interval,
+        this is common for maintenance tasks which need to be performed monthly,
+        every 6 months, every year, etc.
+
+        Alternatively, you might be defining a work calendar, which defines
+        working days or holidays. The working days might be every week from
+        monday to friday ("every" week means it recurs every week), or the
+        holidays might be the same every year.
+
+        The types of recurrence are:
+
+        - DAILY: every Nth (interval) day for up to X (Occurrences) occurrences.
+            e.g. Every day, every 2 days, every day up to 5 times, etc
+        - WEEKLY: every Nth (interval) MTWTFSS (WeekdayComponent) for up to X
+            (Occurrences) occurrences. e.g. Every Monday, every weekday, every
+            other saturday, etc
+        - MONTHLY_BY_DAY_OF_MONTH: every Nth (DayComponent) of every Xth
+            (Interval) Month up to Y (Occurrences) occurrences. e.g. Every 15th of
+            the Month.
+        - MONTHLY_BY_POSITION: Every Nth (Position) MTWTFSS (WeekdayComponent)
+            of every Xth (Interval) Month up to Y (Occurrences) occurrences. e.g.
+            Every second Tuesday of the Month.
+        - YEARLY_BY_DAY_OF_MONTH: every Nth (DayComponent) of every JFMAMJJASOND
+            (MonthComponent) month of every Yth (Interval) Year up to Z
+            (Occurrences) occurrences. e.g. every 25th of December.
+        - YEARLY_BY_POSITION: every Nth (Position) MTWTFSS (WeekdayComponent) of
+            every JFMAMJJASOND (MonthComponent) month of every Yth (Interval)
+            Year up to Z (Occurrences) occurrences. e.g. every third Wednesday
+            of January.
+
+        These recurrence patterns are fairly standard in all calendar and
+        scheduling applications.
+
+        :param parent: Either an IfcTaskTimeRecurring if you are defining a
+            recurring schedule for a task, or IfcWorkTime if you are defining a
+            recurring pattern for a workdays or holidays in a calendar.
+        :type parent: ifcopenshell.entity_instance.entity_instance
+        :param recurrence_type: One of the types of recurrences.
+        :type recurrence_type: str
+        :return: The newly created IfcRecurrencePattern
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            # Let's create a new calendar.
+            calendar = ifcopenshell.api.run("sequence.add_work_calendar", model)
+
+            # Let's start defining the times that we work during the week.
+            work_time = ifcopenshell.api.run("sequence.add_work_time", model,
+                work_calendar=calendar, time_type="WorkingTimes")
+
+            # We create a weekly recurrence
+            pattern = ifcopenshell.api.run("sequence.assign_recurrence_pattern", model,
+                parent=work_time, recurrence_type="WEEKLY")
+
+            # State that we work from weekdays 1 to 5 (i.e. Monday to Friday)
+            ifcopenshell.api.run("sequence.edit_recurrence_pattern", model,
+                recurrence_pattern=pattern, attributes={"WeekdayComponent": [1, 2, 3, 4, 5]})
+
+            # Let's imagine we are creating a maintenance schedule.
+            schedule = ifcopenshell.api.run("sequence.add_work_schedule", model, name="Equipment Maintenance")
+
+            # Now let's imagine we have a task to maintain the chillers
+            task = ifcopenshell.api.run("sequence.add_task", model,
+                work_schedule=schedule, name="Chiller maintenance")
+
+            # Because it is a maintenance task, we must schedule a recurring time
+            time = ifcopenshell.api.run("sequence.add_task_time", model, task=task, is_recurring=True)
+
+            # We create a monthly recurrence
+            pattern = ifcopenshell.api.run("sequence.assign_recurrence_pattern", model,
+                parent=work_time, recurrence_type="MONTHLY_BY_DAY_OF_MONTH")
+
+            # Specifically, the maintenance task must occur every 6 months
+            ifcopenshell.api.run("sequence.edit_recurrence_pattern", model,
+                recurrence_pattern=pattern, attributes={"DayComponent": [1], "Interval": 6})
+        """
         self.file = file
-        self.settings = {"parent": None, "recurrence_type": "WEEKLY"}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"parent": parent, "recurrence_type": recurrence_type}
 
     def execute(self):
         recurrence = self.file.createIfcRecurrencePattern(