Write documentation for spatial API module

src/ifcopenshell-python/ifcopenshell/api/spatial/reference_structure.py

@@ -21,14 +21,64 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, product=None, relating_structure=None):
+        """Denote that a product is related to a spatial structure
+
+        This is similar to ifcopenshell.api.spatial.assign_container, except
+        that containment can only occur between a product and a single spatial
+        structure element. This is fine if a wall is on level 1, but not
+        appropriate if you have a multistorey column on multiple levels, or a
+        door with a to and from space, or a stair going from one floor to
+        another floor. This is where spatial referencing is used.
+
+        Typically, the product will be contained in the lowermost, constructed
+        first, or primarily accessible space. For a multistorey column or stair,
+        the column or stair will therefore be contained in the lowermost storey.
+        Then, any other storeys will be referenced.
+
+        Referencing is non-hierarchical, so a door may be referenced in multiple
+        spaces simultaneously.
+
+        :param product: The physical IfcElement that exists in the space.
+        :type product: ifcopenshell.entity_instance.entity_instance
+        :param relating_structure: The IfcSpatialStructureElement element, such
+            as IfcBuilding, IfcBuildingStorey, or IfcSpace that the element
+            exists in.
+        :return: The IfcRelContainedInSpatialStructure relationship instance
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            project = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcProject")
+            site = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcSite")
+            building = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuilding")
+            storey1 = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuildingStorey")
+            storey2 = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuildingStorey")
+            storey3 = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuildingStorey")
+
+            # The project contains a site (note that project aggregation is a special case in IFC)
+            ifcopenshell.api.run("aggregate.assign_object", model, product=site, relating_object=project)
+
+            # The site has a building, the building has a storey, and the storey has a space
+            ifcopenshell.api.run("aggregate.assign_object", model, product=building, relating_object=site)
+            ifcopenshell.api.run("aggregate.assign_object", model, product=storey, relating_object=building)
+            ifcopenshell.api.run("aggregate.assign_object", model, product=space, relating_object=storey)
+
+            # Create a column, this column spans 3 storeys
+            column = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcWall")
+
+            # The column is contained in the lowermost storey
+            ifcopenshell.api.run("spatial.assign_container", model, product=column, relating_structure=storey1)
+
+            # And referenced in the others
+            ifcopenshell.api.run("spatial.reference_structure", model, product=column, relating_structure=storey2)
+            ifcopenshell.api.run("spatial.reference_structure", model, product=column, relating_structure=storey3)
+        """
         self.file = file
         self.settings = {
-            "product": None,
-            "relating_structure": None,
+            "product": product,
+            "relating_structure": relating_structure,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         referenced_in_structures = self.settings["product"].ReferencedInStructures