Write docs for style API module

src/ifcopenshell-python/ifcopenshell/api/style/edit_surface_style.py

@@ -18,11 +18,57 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, style=None, attributes=None):
+        """Edits the attributes of an IfcPresentationItem
+
+        For more information about the attributes and data types of an
+        IfcPresentationItem, consult the IFC documentation.
+
+        The IfcPresentationItem is expected to be one of IfcSurfaceStyleShading,
+        IfcSurfaceStyleRendering, IfcSurfaceStyleWithTextures,
+        IfcSurfaceStyleLighting, IfcSurfaceStyleReflectance, or
+        IfcExternallyDefinedSurfaceStyle.
+
+        To represent a colour, a nested dictionary should be used. See the
+        example below.
+
+        :param style: The IfcPresentationStyle entity you want to edit
+        :type style: ifcopenshell.entity_instance.entity_instance
+        :param attributes: a dictionary of attribute names and values.
+        :type attributes: dict, optional
+        :return: None
+        :rtype: None
+
+        Example::
+
+            # Create a new surface style
+            style = ifcopenshell.api.run("style.add_style", model)
+
+            # Create a blank rendering style.
+            rendering = ifcopenshell.api.run("style.add_surface_style", model,
+                style=style, ifc_class="IfcSurfaceStyleRendering")
+
+            # Edit the attributes of the rendering style.
+            ifcopenshell.api.run("style.edit_surface_style", model,
+                style=rendering, attributes={
+                    # A surface colour and transparency is still supplied for
+                    # viewport display only. This will supersede the shading
+                    # presentation item.
+                    "SurfaceColour": { "Name": None, "Red": 1.0, "Green": 0.8, "Blue": 0.8 },
+                    "Transparency": 0., # 0 is opaque, 1 is transparent
+
+                    # NOTDEFINED is assumed to be a PHYSICAL (PBR) lighting
+                    # model. In IFC4X3, you may choose PHYSICAL directly.
+                    "ReflectanceMethod": "NOTDEFINED",
+
+                    # For PBR shading, you may specify these parameters:
+                    "DiffuseColour": { "Name": None, "Red": 0.9, "Green": 0.8, "Blue": 0.8 },
+                    "SpecularColour": 0.1, # Metallic factor
+                    "SpecularHighlight": {"SpecularRoughness": 0.5}, # Roughness factor
+                })
+        """
         self.file = file
-        self.settings = {"style": None, "attributes": {}}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"style": style, "attributes": attributes or {}}
 
     def execute(self):
         for key, value in self.settings["attributes"].items():