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

src/ifcopenshell-python/docs/conf.py

@@ -28,19 +28,19 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
 
 
 # -- Project information -----------------------------------------------------
 
 project = "IfcOpenShell"
-copyright = "2020, IfcOpenShell Contributors"
+copyright = "2020-2022, IfcOpenShell Contributors"
 author = "IfcOpenShell Contributors"
 
 # The full version, including alpha/beta/rc tags
-release = "0.0.1"
+release = "0.7.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -48,7 +48,34 @@ release = "0.0.1"
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc"]
+
+# I considered autodoc+autosummary but it had showstopper glitches:
+# - Some modules couldn't be accessed https://github.com/sphinx-doc/sphinx/issues/7912#issuecomment-1120508738
+# - No subnav making it really hard to navigate
+# - Kinda hacky setup https://stackoverflow.com/questions/2701998/sphinx-autodoc-is-not-automatic-enough
+# - I couldn't customise the template to show submodules above members which makes API discovery hard for users
+extensions = ["autoapi.extension"]
+
+# We're only documenting Python here
+autoapi_type = 'python'
+
+# autoapi works by reading source code instead of importing modules
+autoapi_dirs = ['../ifcopenshell']
+
+# autoapi_options doesn't have show-module-summary, as it tends to create one
+# page per function which contradicts the presentation of showing all functions
+# as a list. This creates two possible locations where a function is documented
+# which is really disorienting. I also exclude imported-members. For example,
+# ifcopenshell.file is imported from ifcopenshell.file.file, but it gets pretty
+# confusing to see the docs again in multiple places (seriously,
+# ifcopenshell.file.file is everywhere).
+autoapi_options = ['members', 'undoc-members', 'private-members', 'special-members', 'show-inheritance']
+
+# This option is set to both to allow both class docstrings and __init__ docstrings.
+autoapi_python_class_content = 'both'
+
+# Group by type (e.g. attribute, class, function, etc) then alphabetically.
+autoapi_member_order = "groupwise"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

src/ifcopenshell-python/docs/ifcopenshell-python.rst

@@ -8,8 +8,8 @@ this document.
    :maxdepth: 1
    :caption: Contents:
 
-   ifcopenshell-python/quickstart
-   ifcopenshell-python/api-documentation
+   ifcopenshell-python/hello_world
+   ifcopenshell-python/developer_guide
 
 Indices and tables
 ------------------

src/ifcopenshell-python/docs/ifcopenshell-python/api-documentation.rst

@@ -1,21 +0,0 @@
-API Documentation
-=================
-
-.. automodule:: ifcopenshell.entity_instance
-   :members:
-
-.. automodule:: ifcopenshell.file
-   :members:
-
-.. automodule:: ifcopenshell.guid
-   :members:
-
-
-.. automodule:: ifcopenshell.template
-   :members:
-
-.. automodule:: ifcopenshell.validate
-   :members:
-
-.. automodule:: ifcopenshell.ids
-   :members:

src/ifcopenshell-python/docs/ifcopenshell-python/developer_guide.rst

@@ -0,0 +1,15 @@
+Developer Guide
+===============
+
+The core module implements low-level functionality to read and write IFC data. This includes:
+
+- Reading IFC data from different serialisations into Python objects
+- Accessing direct and indirect attributes of IFC entities
+- Creating IFC entities
+- Generating GlobalIds
+- Removing IFC entities and all references
+- Modifying IFC direct attributes
+- Checking IFC class inheritance
+- Validating IFC data
+
+TODO

src/ifcopenshell-python/docs/ifcopenshell-python/hello_world.rst

@@ -1,5 +1,7 @@
-Quickstart
-==========
+Hello, world!
+=============
 
 For starters, you can read `Using IfcOpenShell to parse IFC files with Python
 <https://thinkmoult.com/using-ifcopenshell-parse-ifc-files-python.html>`_
+
+TODO

src/ifcopenshell-python/docs/index.rst

@@ -1,20 +1,20 @@
 Let's learn IfcOpenShell
 ========================
 
-IfcOpenShell is a 
+IfcOpenShell is a suite of developer libraries and utilities to manipulate OpenBIM data.
 
-A coloured icon: :octicon:`report;1em;sd-text-info`, some more text.
+.. note::
 
-:bdg:`plain badge`
+   This documentation is incomplete. Would you like to help write more? `Get in touch! <https://osarch.org/chat/>`__
 
 .. toctree::
+   :hidden:
    :maxdepth: 1
    :caption: Contents:
 
    ifcopenshell
    ifcopenshell-python
    ifcconvert
-   blenderbim
    bimtester
    ifcdiff
    ifcclash

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)

src/ifcopenshell-python/ifcopenshell/api/__init__.py

@@ -16,6 +16,8 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""High level user-oriented IFC authoring capabilities"""
+
 import json
 import numpy
 import importlib

src/ifcopenshell-python/ifcopenshell/api/aggregate/__init__.py

@@ -0,0 +1,24 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Aggregates are the concept of breaking down larger wholes into smaller parts.
+
+One common use is spatial elements, such as how a site has multiple buildings,
+and a building has multiple storeys. Another is for regular elements, such as
+how a wall is made out of members and coverings.
+"""

src/ifcopenshell-python/ifcopenshell/api/aggregate/assign_object.py

@@ -21,14 +21,24 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, product=None, relating_object=None):
+        """Assigns an object as an aggregate to a product
+
+        :param product: The part of the aggregate
+        :param relating_object: The whole of the aggregate
+        :return: entity: The aggregate relationship
+
+        Example::
+
+            element = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcSite")
+            subelement = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuilding")
+            ifcopenshell.api.run("aggregate.assign_object", model, product=subelement, relating_object=element)
+        """
         self.file = file
         self.settings = {
-            "product": None,
-            "relating_object": None,
+            "product": product,
+            "relating_object": relating_object,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         decomposes = None

src/ifcopenshell-python/ifcopenshell/api/attribute/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/boundary/__init__.py

@@ -0,0 +1,21 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Boundaries are primarily used for representing virtual interfaces between
+spaces for energy analysis.
+"""

src/ifcopenshell-python/ifcopenshell/api/classification/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/constraint/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/context/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/control/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/cost/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/document/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/drawing/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/geometry/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/georeference/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/grid/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/group/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/layer/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

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

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/material/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/nest/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/owner/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/profile/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/project/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/pset/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/pset_template/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/resource/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/root/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/sequence/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

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

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/structural/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

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

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/system/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/type/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/unit/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/api/void/__init__.py

@@ -0,0 +1,17 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2022 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.

src/ifcopenshell-python/ifcopenshell/draw.py

@@ -16,6 +16,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""2D drawing generation and serialisation"""
 
 import math
 import json

src/ifcopenshell-python/ifcopenshell/entity_instance.py

@@ -88,7 +88,7 @@ for nm in ifcopenshell_wrapper.schema_names():
 
 
 class entity_instance(object):
-    """This is the base Python class for all IFC objects.
+    """Base class for all IFC objects.
 
     An instantiated entity_instance will have methods of Python and the IFC class itself.
 

src/ifcopenshell-python/ifcopenshell/file.py

@@ -180,14 +180,12 @@ class file(object):
 
         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
+        print(products[0].id(), products[0].GlobalId) # 122 2XQ$n5SLP5MBLyL442paFx
+        print(products[0] == ifc_file[122] == ifc_file["2XQ$n5SLP5MBLyL442paFx"]) # True
     """
 
     def __init__(self, f=None, schema=None):
+        """Create a new file object"""
         if f is not None:
             self.wrapped_data = f
         else:
@@ -247,12 +245,12 @@ class file(object):
         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',$,$,$,$,$,$,$)
+            f.create_entity("IfcPerson")
+            # >>> #1=IfcPerson($,$,$,$,$,$,$,$)
+            f.create_entity("IfcPerson", "Foobar")
+            # >>> #2=IfcPerson('Foobar',$,$,$,$,$,$,$)
+            f.create_entity("IfcPerson", Identification="Foobar")
+            # >>> #3=IfcPerson('Foobar',$,$,$,$,$,$,$)
         """
         eid = kwargs.pop("id", -1)
 

src/ifcopenshell-python/ifcopenshell/geom/__init__.py

@@ -16,6 +16,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Geometry processing and analysis"""
 
 from __future__ import absolute_import
 from __future__ import division

src/ifcopenshell-python/ifcopenshell/guid.py

@@ -16,6 +16,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Reads and writes encoded GlobalIds"""
 
 from __future__ import absolute_import
 from __future__ import division

src/ifcopenshell-python/ifcopenshell/util/__init__.py

@@ -15,3 +15,5 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Utility functions for common IFC queries"""

src/ifcopenshell-python/ifcopenshell/validate.py

@@ -16,6 +16,8 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Data validation module"""
+
 from __future__ import print_function
 
 import sys