Add documentation for IfcPatch

src/ifcopenshell-python/docs/ifcpatch.rst

@@ -0,0 +1,78 @@
+IfcPatch
+========
+
+IfcPatch is both a CLI utility and library that lets you run a predetermined
+modification on an IFC file, known as a patch recipe. This is great for running
+prepackaged scripts on IFC models on a server with a standardised interface.
+It's also great for distributing little scripts that need to modify an IFC to
+users who don't know how to code or aren't interested in knowing the details.
+
+Source installation
+-------------------
+
+1. :doc:`Install IfcOpenShell <ifcopenshell-python/installation>`
+2. `Clone the source code <https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.7.0/src/ifcpatch>`_.
+3. ``cd /path/to/src/ifcpatch``
+
+Here is a minimal example of how to use IfcPatch as a Python module or CLI
+utility:
+
+::
+
+    $ python -m ifcpatch -h
+
+    usage: __main__.py [-h] -i INPUT [-o OUTPUT] -r RECIPE [-l LOG]
+                       [-a ARGUMENTS [ARGUMENTS ...]]
+
+    Patches IFC files to fix badly formatted data
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      -i INPUT, --input INPUT
+                            The IFC file to patch
+      -o OUTPUT, --output OUTPUT
+                            The output file to save the patched IFC
+      -r RECIPE, --recipe RECIPE
+                            Name of the recipe to use when patching
+      -l LOG, --log LOG     Specify a log file
+      -a ARGUMENTS [ARGUMENTS ...], --arguments ARGUMENTS [ARGUMENTS ...]
+                            Specify custom arguments to the patch recipe
+
+Exactly how it is run depends on the recipe. A recipe may require zero or more
+arguments which are specific to the recipe. Here's an example which runs the
+`ExtractElements` recipe, which, as the same suggests, extracts out elements.
+This recipe expects one argument, which uses the [IFC Query
+syntax](https://wiki.osarch.org/index.php?title=IfcOpenShell_code_examples#IFC_Query_Syntax).
+In this example, we'll extract out all `IfcWall` elements.
+
+::
+
+    $ ifcpatch -i input.ifc -o output.ifc -r ExtractElements -a ".IfcWall"
+    $ cat output.ifc
+
+Here is a minimal example of how to use IfcDiff as a library:
+
+.. code-block:: python
+
+    import ifcpatch
+
+    ifcpatch.execute({
+        "input": "input.ifc",
+        "output": "output.ifc",
+        "recipe": "ExtractElements",
+        "log": "ifcpatch.log",
+        "arguments": [".IfcWall"],
+    })
+
+You can also alias it to a command:
+
+::
+
+    $ alias ifcpatch='python -m ifcpatch'
+
+Alternatively, you can package it as an executable.
+
+::
+
+    $ python make.py
+    $ ./dist/ifcpatch