Add docs for library API module

src/ifcopenshell-python/ifcopenshell/api/library/add_library.py

@@ -22,11 +22,45 @@ import ifcopenshell.util.date
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, name=None):
+        """Adds a new library to the project
+
+        A library is an external data source that is related to the project. It
+        may be a database, a spreadsheet, an API, or even a stack of papers in a
+        filing cabinet. This allows IFC data to store relationships to these
+        external data sources.
+
+        For example, you may have a list of laser scans of a site stored in an
+        online platform, which can be queried using an API. Or, you might have a
+        database of live building sensor data. So long as there is a clear
+        identifier you can use to link the two datasets together, you can create
+        a relationship.
+
+        Note that IFC does not store any instructions on how to access the
+        library. It does not specify whether a HTTP request or database
+        connection needs to be made or what protocol the library operates with.
+        Until this is fleshed out further, it is the users responsibility to
+        name the libraries consistently and use appropriate identifiers. For
+        example, if you are linking IFC data and Brickschema data, use a full
+        URI for the identifier with no abbreviation (e.g.
+        'http://example.org/digitaltwin#AHU01', not 'digitaltwin:AHU01').
+
+        A library will then contain a list of references within that library.
+        These references will then be related to IFC elements. For example, a
+        library will represent an external database, and a reference will point
+        to a particular table and row within that database.
+
+        :param name: The name of the library
+        :type name: str
+        :return: The newly created IfcLibraryInformation
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            ifcopenshell.api.run("library.add_library", model, name="Brickschema")
+        """
         self.file = file
-        self.settings = {"name": None}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"name": name}
 
     def execute(self):
         return self.file.create_entity("IfcLibraryInformation", Name=self.settings["name"])