Migrate documentation for IfcTester and make optional deps mandatory in PyPI

I don't like this, but PyPI makes it really, really hard to "discover" optional deps and what they're used for. So it's just easier to make it a mandatory dependency and advanced users can always strip it out. This stops user reports about "it doesn't work out of the box I only did pip install ifctester"
2026-08-09 17:31:45 +00:00 · 2025-02-16 07:46:22 +11:00
parent 6ac6f13018
commit aad4dad9a7
3 changed files with 95 additions and 62 deletions
@@ -11,3 +11,96 @@ PyPI
 .. code-block::

    pip install ifctester
+
+Examples
+--------
+
+You can execute IfcTester using a CLI.
+
+.. code-block:: console
+
+    # Validate an IFC with an IDS and report to console
+    python -m ifctester example.ids example.ifc
+
+    # Generate a HTML report instead
+    python -m ifctester example.ids example.ifc -r Html -o report.html
+
+Alternatively, you can use Python:
+
+.. code-block:: python
+
+    import ifcopenshell
+    from ifctester import ids, reporter
+
+    # Create new IDS
+    specs = ids.Ids(title="My IDS")
+
+    # add specification to it
+    spec = ids.Specification(name="My first specification")
+    spec.applicability.append(ids.Entity(name="IFCWALL"))
+    requirement = ids.Property(
+        baseName="IsExternal",
+        value="TRUE", 
+        propertySet="Pset_WallCommon", 
+        dataType="IfcBoolean",
+        uri="https://identifier.buildingsmart.org/uri/.../prop/LoadBearing", 
+        instructions="Walls need to be load bearing.",
+        cardinality="required")
+    spec.requirements.append(requirement)
+    specs.specifications.append(spec)
+
+    # Save to a file
+    specs.to_xml("IDS.xml")
+
+    # Open IFC file:
+    my_ifc = ifcopenshell.open("model.ifc")
+
+    # Validate IFC model against IDS requirements:
+    specs.validate(my_ifc)
+
+    # Show results in a console
+    reporter.Console(specs).report()
+
+    # Alternatively, to JSON
+    report = reporter.Json(specs)
+    report.report()
+    report.to_file("report.json")
+
+    # Or to ODS spreadsheet
+    report = reporter.Ods(specs)
+    report.report()
+    report.to_file("report.ods")
+
+    # Or to HTML spreadsheet
+    report = reporter.Html(specs)
+    report.report()
+    report.to_file("report.html")
+
+    # Or to BCF
+    report = reporter.Bcf(specs)
+    report.report()
+    report.to_file("report.bcf")
+
+CLI manual
+----------
+
+.. code-block:: console
+
+    $ python -m ifctester -h
+
+    usage: __main__.py [-h] [-r REPORTER] [--no-color] [--excel-safe] [-o OUTPUT] ids [ifc]
+
+    Uses an IDS to audit an IFC
+
+    positional arguments:
+      ids                   Path to an IDS
+      ifc                   Path to an IFC
+
+    options:
+      -h, --help            show this help message and exit
+      -r REPORTER, --reporter REPORTER
+                            The reporting method to view audit results
+      --no-color            Disable colour output (supported by Console reporting)
+      --excel-safe          Make sure exported ODS is safely exported for Excel
+      -o OUTPUT, --output OUTPUT
+                            Output file (supported for all types of reporting except Console)