Add sphinx docstrings to ifcopenshell python binding

src/ifcopenshell-python/ifcopenshell/file.py

@@ -36,24 +36,20 @@ except NameError:
 
 
 class file(object):
-    """
-    Base class for containing IFC files.
+    """Base class for containing IFC files.
 
     Class has instance methods for filtering by element Id, Type, etc.
-
     Instantiated objects can be subscripted by Id or Guid
 
-    example:
+    Example::
 
-    ifc_file = ifcopenshell.open(file_path)
-    products = ifc_file.by_type("IfcProduct")
-
-    print(products[0].id(), products[0].GlobalId)
-    >>> 122 2XQ$n5SLP5MBLyL442paFx
-
-    # Subscripting
-    print(products[0] == ifc_file[122] == ifc_file['2XQ$n5SLP5MBLyL442paFx'])
-    >>> True
+        ifc_file = ifcopenshell.open(file_path)
+        products = ifc_file.by_type("IfcProduct")
+        print(products[0].id(), products[0].GlobalId)
+        >>> 122 2XQ$n5SLP5MBLyL442paFx
+        # Subscripting
+        print(products[0] == ifc_file[122] == ifc_file['2XQ$n5SLP5MBLyL442paFx'])
+        >>> True
     """
     def __init__(self, f=None, schema=None):
         if f is not None:
@@ -64,6 +60,25 @@ class file(object):
             self.wrapped_data = ifcopenshell_wrapper.file(*args)
 
     def create_entity(self, type, *args, **kwargs):
+        """Create a new IFC entity in the file.
+
+        :param type: Case insensitive name of the IFC class
+        :type type: string
+        :param args: The positional arguments of the IFC class
+        :param kwargs: The keyword arguments of the IFC class
+        :returns: An entity instance
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            f = ifcopenshell.file()
+            f.create_entity('IfcPerson')
+            >>> #1=IfcPerson($,$,$,$,$,$,$,$)
+            f.create_entity('IfcPerson', 'Foobar')
+            >>> #2=IfcPerson('Foobar',$,$,$,$,$,$,$)
+            f.create_entity('IfcPerson', Identification='Foobar')
+            >>> #3=IfcPerson('Foobar',$,$,$,$,$,$,$)
+        """
         e = entity_instance((self.schema, type))
         self.wrapped_data.add(e.wrapped_data)
         e.wrapped_data.this.disown()
@@ -86,42 +101,73 @@ class file(object):
             return entity_instance(self.wrapped_data.by_guid(str(key)))
 
     def by_id(self, id):
-        """
-        Return IFC objects filtered by IFC ID.
+        """Return IFC objects filtered by IFC ID.
 
-        Returned objects are unwrapped IFC objects.
+        :param id: STEP numerical identifier
+        :type id: int
+        :returns: Returned objects are unwrapped IFC objects.
+        :rtype: ifcopenshell.entity_instance.entity_instance
         """
         return self[id]
 
     def by_guid(self, guid):
-        """
-        Return IFC objects filtered by IFC GUID.
+        """Return IFC objects filtered by IFC GUID.
 
-        Returned objects are unwrapped IFC objects.
+        :param guid: GlobalId value in 22-character encoded form
+        :type guid: string
+        :returns: Returned objects are unwrapped IFC objects.
+        :rtype: ifcopenshell.entity_instance.entity_instance
         """
         return self[guid]
 
     def add(self, inst):
+        """Undocumented function"""
         inst.wrapped_data.this.disown()
         return entity_instance(self.wrapped_data.add(inst.wrapped_data))
 
     def by_type(self, type):
-        """
-        Return IFC objects filtered by IFC Type and wrapped with the entity_instance class.
+        """Return IFC objects filtered by IFC Type and wrapped with the entity_instance class.
 
-        See ifcopenshell.entity_instance for class methods and properties
+        :param type: The case insensitive type of IFC class to return.
+        :type type: string
+        :returns: A list of ifcopenshell.entity_instance.entity_instance objects
+        :rtype: list
         """
         return [entity_instance(e) for e in self.wrapped_data.by_type(type)]
 
     def traverse(self, inst, max_levels=None):
+        """Get a list of all referenced entities for a particular entity
+
+        :param inst: The entity instance to get all sub instances
+        :type inst: ifcopenshell.entity_instance.entity_instance
+        :param max_levels: How far deep to recursively fetch sub instances. None or -1 means infinite.
+        :type max_levels: None|int
+        :returns: A list of ifcopenshell.entity_instance.entity_instance objects
+        :rtype: list
+        """
         if max_levels is None:
             max_levels = -1
         return [entity_instance(e) for e in self.wrapped_data.traverse(inst.wrapped_data, max_levels)]
 
     def get_inverse(self, inst):
+        """Return a list of entities that reference this entity
+
+        :param inst: The entity instance to get inverse relationships
+        :type inst: ifcopenshell.entity_instance.entity_instance
+        :returns: A list of ifcopenshell.entity_instance.entity_instance objects
+        :rtype: list
+        """
         return [entity_instance(e) for e in self.wrapped_data.get_inverse(inst.wrapped_data)]
 
     def remove(self, inst):
+        """Deletes an IFC object in the file.
+
+        Other entities that reference the deleted object will be set to null.
+
+        :param inst: The entity instance to delete
+        :type inst: ifcopenshell.entity_instance.entity_instance
+        :rtype: None
+        """
         return self.wrapped_data.remove(inst.wrapped_data)
 
     def __iter__(self):