Fix #4914. Write docs for syntax and schema validation and schema querying

src/ifcopenshell-python/docs/bsdd.rst

@@ -43,6 +43,7 @@ Examples
 Learning how to use the bSDD is best done by reading the official Swagger API docs.
 
 .. code-block:: python
+
     from bsdd import Client,apply_ifc_classification_properties
     from pprint import pprint
 

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

@@ -17,4 +17,5 @@ capabilities of the C++ core are available in Python.
    ifcopenshell-python/geometry_creation
    ifcopenshell-python/geometry_tree
    ifcopenshell-python/selector_syntax
-   ifcopenshell-python/developer_guide
+   ifcopenshell-python/schema_querying
+   ifcopenshell-python/validation

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

@@ -1,15 +0,0 @@
-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/schema_querying.rst

@@ -0,0 +1,73 @@
+Schema querying
+===============
+
+Schema declarations
+-------------------
+
+IfcOpenShell can query the IFC schema itself without instantiating or loading an IFC dataset.
+
+.. code-block:: python
+
+    import ifcopenshell
+    ifc4 = ifcopenshell.schema_by_name("IFC4")
+
+A schema definition is known as a declaration. You may loop through all declarations or retrieve a declaration by name. All declarations have a name.
+
+.. code-block:: python
+
+    for declaration in ifc4.declarations():
+        print(declaration.name()) # 'IfcAbsorbedDoseMeasure', 'IfcAccelerationMeasure', 'IfcActionRequest', ...
+
+    ifcwall = ifc4.declaration_by_name("IfcWall")
+
+You can check if an entity is abstract, and retrive both the supertype and subtypes of an entity:
+
+.. code-block:: python
+
+    print(ifcwall.is_abstract()) # False
+    print(ifcwall.supertype()) # <entity IfcBuildingElement>
+    print(ifcwall.subtypes()) # (<entity IfcWallElementedCase>, <entity IfcWallStandardCase>)
+
+You can retrieve only the direct attributes of an entity, or all the direct attributes including inherited attributes, or inverse attributes:
+
+.. code-block:: python
+
+    print(ifcwall.attributes())
+    print(ifcwall.all_attributes())
+    print(ifcwall.all_inverse_attributes())
+
+buildingSMART property set templates
+------------------------------------
+
+For each IFC schema version, buildingSMART publishes built in property and quantity set templates for standardised properties. These define property names, property sets, data types, and which IFC class they are applicable to. You can query these templates.
+
+.. code-block:: python
+
+    import ifcopenshell.util.pset
+    templates = ifcopenshell.util.pset.PsetQto("IFC4")
+
+To get just the names of applicable templates for an entity:
+
+.. code-block:: python
+
+    # ['Pset_EnvironmentalImpactIndicators', 'Pset_EnvironmentalImpactValues', 'Pset_WallCommon', 'Qto_WallBaseQuantities', ...]
+    print(templates.get_applicable_names("IfcWall"))
+
+They may also be retrieved as an ``IfcPropertySetTemplate`` entity:
+
+.. code-block:: python
+
+    print(templates.get_applicable("IfcWall"))
+
+A single template may be retrieved by name:
+
+.. code-block:: python
+
+    templates.get_by_name('Pset_WallCommon')
+
+You may add your own IFC files containing pset template definitions:
+
+.. code-block:: python
+
+    my_pset_library = ifcopenshell.open('/path/to/library.ifc')
+    templates.templates.append(my_pset_library)

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

@@ -0,0 +1,78 @@
+Validation
+==========
+
+SPF syntax validation
+---------------------
+
+IfcOpenShell can validate whether or not an IFC-SPF file contains correct SPF syntax.
+
+.. code-block::
+
+    $ python -m ifcopenshell.simple_spf path/to/model.ifc
+    Valid
+
+Here are some examples of failures:
+
+.. code-block::
+
+    $ python -m ifcopenshell.simple_spf fixtures/fail_double_comma.ifc
+    On line 8 column 21:
+    Unexpected comma (',')
+    Expecting one of DBLQUOTE DOT HASH INT LPAR NONE QUOTE REAL STAR UPPER
+    00008 | #1=IFCPERSON($,$,'',,$,$,$,$);
+                                ^
+
+    $ python -m ifcopenshell.simple_spf fixtures/fail_double_semi.ifc
+    On line 27 column 66:
+    Unexpected semicolon (';')
+    Expecting one of ENDSEC HASH
+    00027 | #20=IFCPROJECT('2AyG2X0sb16Bjd4gQc07yZ',#5,'',$,$,$,$,(#11),#19);;
+                                                                             ^
+
+    $ python -m ifcopenshell.simple_spf fixtures/fail_duplicate_id.ifc
+    On line 27:
+    Duplicate instance name #19
+    00027 | #19=IFCPROJECT('2AyG2X0sb16Bjd4gQc07yZ',#5,'',$,$,$,$,(#11),#19);
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    $ python -m ifcopenshell.simple_spf fixtures/fail_no_header.ifc
+    On line 2 column 1:
+    Unexpected hex ('F')
+    Expecting HEADER
+    00002 | FILE_DESCRIPTION(('ViewDefinition [CoordinationView]'),'2;1');
+            ^
+
+The optional ``--json`` argument may be used to instead get results in JSON.
+
+.. code-block::
+
+    $ python -m ifcopenshell.simple_spf test.ifc
+    {"type": "unexpected_token", "lineno": 8, "column": 48, "found_type": "semicolon", "found_value": ";", "expected": ["ENDSEC"], "line": "#1= IFCPERSON($,'Nicht definiert',$,$,$,$,$,$);;", "message": "On line 8 column 48:\nUnexpected semicolon (';')\nExpecting ENDSEC\n00008 | #1= IFCPERSON($,'Nicht definiert',$,$,$,$,$,$);;\n                                                       ^"}
+
+IFC schema validation
+---------------------
+
+IfcOpenShell can validate models against the IFC schema itself. It checks against attributes, entity names, data types, cardinality, and where rules.
+
+.. code-block:: console
+
+    $ python -m ifcopenshell.validate -h
+
+    usage: validate.py [-h] [--rules] [--json] [--fields] [--spf] files [files ...]
+
+    positional arguments:
+      files       The IFC file to validate.
+
+    options:
+      -h, --help  show this help message and exit
+      --rules     Run express rules.
+      --json      Output in JSON format.
+      --fields    Output more detailed information about failed entities (only with --json).
+      --spf       Output entities in SPF format (only with --json).
+
+
+For example:
+
+.. code-block:: bash
+
+    python -m ifcopenshell.validate /path/to/model.ifc --rules