#2185 Set up auto generated API reference documentation via sphinx-autoapi

src/ifcopenshell-python/ifcopenshell/__init__.py

@@ -16,6 +16,17 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""The entry module for IfcOpenShell
+
+Typically used for opening an IFC via a filepath, or accessing one of the
+submodules.
+
+Example::
+
+    import ifcopenshell
+    print(ifcopenshell.version) # v0.7.0-1b1fd1e6
+    model = ifcopenshell.open("/path/to/model.ifc")
+"""
 
 from __future__ import absolute_import
 from __future__ import division
@@ -60,14 +71,27 @@ UNSUPPORTED_SCHEMA = ifcopenshell_wrapper.file_open_status.UNSUPPORTED_SCHEMA
 
 
 class Error(Exception):
+    """Error used when a generic problem occurs"""
     pass
 
 
 class SchemaError(Error):
+    """Error used when an IFC schema related problem occurs"""
     pass
 
 
 def open(fn):
+    """Loads an IFC dataset from a filepath
+
+    :param fn: Filepath to the IFC model
+    :type fn: string
+    :returns: A file object
+    :rtype: ifcopenshell.file.file
+
+    Example::
+
+        ifc_file = ifcopenshell.open("/path/to/model.ifc")
+    """
     f = ifcopenshell_wrapper.open(os.path.abspath(fn))
     if f.good():
         return file(f)
@@ -84,6 +108,26 @@ def open(fn):
 
 
 def create_entity(type, schema="IFC4", *args, **kwargs):
+    """Creates a new IFC entity that does not belong to an IFC file object
+
+    Note that it is more common to create entities within a existing file
+    object. See :meth:`ifcopenshell.file.file.create_entity`.
+
+    :param type: Case insensitive name of the IFC class
+    :type type: string
+    :param schema: The IFC schema identifier
+    :type schema: 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::
+
+        person = ifcopenshell.create_entity("IfcPerson") # #0=IfcPerson($,$,$,$,$,$,$,$)
+        model = ifcopenshell.file()
+        model.add(person) # #1=IfcPerson($,$,$,$,$,$,$,$)
+    """
     e = entity_instance((schema, type))
     attrs = list(enumerate(args)) + [(e.wrapped_data.get_argument_index(name), arg) for name, arg in kwargs.items()]
     for idx, arg in attrs:
@@ -95,6 +139,17 @@ gcroot = []
 
 
 def register_schema(schema):
+    """Registers a custom IFC schema
+
+    :param schema: A schema object
+    :type schema: ifcopenshell.express.schema_class.SchemaClass
+
+    Example::
+
+        schema = ifcopenshell.express.parse("/path/to/ifc-custom.exp")
+        ifcopenshell.register_schema(schema)
+        ifcopenshell.file(schema="IFC_CUSTOM")
+    """
     gcroot.append(schema)
     ifcopenshell_wrapper.register_schema(schema.schema)
     register_schema_attributes(schema.schema)