docs: add DocFX site and GitHub Pages deployment workflow

.config/dotnet-tools.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "docfx": {
+      "version": "2.81.0",
+      "commands": [
+        "docfx"
+      ],
+      "rollForward": false
+    }
+  }
+}

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'docfx.json'
+      - '.config/dotnet-tools.json'
+      - 'src/IfcIO/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'docfx.json'
+      - '.config/dotnet-tools.json'
+      - 'src/IfcIO/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-dotnet@v6
+        with:
+          dotnet-version: |
+            8.0.x
+            10.0.x
+      - run: dotnet tool restore
+      - run: dotnet docfx docfx.json --warningsAsErrors
+      # manifest.json records the build machine paths and is not part of the site.
+      - run: rm -f _site/manifest.json
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: _site
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -10,3 +10,7 @@ TestResults/
 *.log
 __pycache__/
 *.pyc
+
+# Documentation site (DocFX output and generated API pages)
+_site/
+docs/api/

docfx.json

@@ -0,0 +1,27 @@
+{
+  "metadata": [
+    {
+      "src": [
+        { "src": "src/IfcIO", "files": ["IfcIO.csproj"] }
+      ],
+      "dest": "docs/api",
+      "properties": { "TargetFramework": "net10.0" },
+      "outputFormat": "apiPage"
+    }
+  ],
+  "build": {
+    "content": [
+      { "src": "docs", "files": ["*.md", "toc.yml", "api/**/*.yml", "api/**/*.md"] }
+    ],
+    "resource": [
+      { "src": "docs", "files": ["images/**"] }
+    ],
+    "output": "_site",
+    "globalMetadata": {
+      "_appTitle": "IfcIO",
+      "_appFooter": "IfcIO is licensed under the MIT License. Not affiliated with buildingSMART.",
+      "_enableSearch": true
+    },
+    "template": ["default", "modern"]
+  }
+}

docs/getting-started.md

@@ -0,0 +1,113 @@
+---
+title: Getting started
+---
+
+# Getting Started with IfcIO
+
+## Installation
+
+### NuGet Package
+
+Install the `IfcIO` library package in your .NET project:
+
+```bash
+dotnet add package IfcIO
+```
+
+### Global CLI Tool
+
+Install the `ifcio` command line tool globally:
+
+```bash
+dotnet tool install --global IfcIO.Cli
+```
+
+---
+
+## Quick Examples
+
+### Reading an IFC File
+
+```csharp
+using IfcIO;
+
+// Open any .ifc or compressed .ifczip file
+var model = IfcModel.Open("Building.ifc");
+
+Console.WriteLine($"Project: {model.Project?.Name}");
+Console.WriteLine($"Total elements: {model.Elements.Count}");
+
+foreach (var storey in model.Storeys)
+{
+    Console.WriteLine($"Storey: {storey.Name} (Elevation: {storey.Elevation}m)");
+}
+```
+
+### Building an IFC4 Model Programmatically
+
+```csharp
+using IfcIO;
+using IfcIO.Geometry;
+
+var model = new IfcModel(IfcSchemaVersion.Ifc4)
+{
+    ProjectName = "Commercial Office Tower",
+    Author = "Engineering Team",
+    Organization = "IOExtend"
+};
+
+var groundFloor = model.AddStorey("Ground Floor", elevation: 0.0);
+
+// Add a wall with modern IFC4 mesh tessellation
+groundFloor.AddWall("Exterior Wall 1", new IfcMeshGeometry(vertices, indices));
+
+// Export to ISO 10303-21 STEP physical file
+model.Save("OfficeTower.ifc");
+
+// Or save compressed as .ifczip
+model.SaveZip("OfficeTower.ifczip");
+```
+
+### Exporting to glTF 2.0 (GLB) and Wavefront OBJ
+
+```csharp
+using IfcIO;
+using IfcIO.Exporters;
+
+var model = IfcModel.Open("Building.ifc");
+
+// Binary glTF 2.0 for 3D web viewers and game engines
+IfcGlbExporter.Export(model, "Building.glb");
+
+// Wavefront OBJ
+IfcObjExporter.Export(model, "Building.obj");
+```
+
+---
+
+## CLI Usage
+
+Run standard operations from your terminal:
+
+```bash
+# Display summary info, schema version, and element counts
+ifcio info Building.ifc
+
+# Convert IFC to binary glTF 2.0 and Wavefront OBJ
+ifcio export Building.ifc --glb scene.glb --obj scene.obj
+
+# Compress IFC to .ifczip
+ifcio pack Building.ifc -o Building.ifczip
+
+# Extract IFC from .ifczip
+ifcio unpack Building.ifczip -o Building.ifc
+
+# Run 3D geometric clash detection with proximity clustering
+ifcio clash Arch.ifc Mep.ifc -o Clashes.json --bcf Clashes.bcfzip --group proximity
+
+# Compare two IFC model revisions (added, deleted, modified)
+ifcio diff Baseline.ifc Revision.ifc -o Changes.json --bcf RevisionChanges.bcfzip
+
+# Validate ISO 10303-21 STEP structure and export BCF issues
+ifcio validate Building.ifc --bcf Issues.bcfzip
+```

docs/index.md

@@ -0,0 +1,38 @@
+---
+title: IfcIO
+---
+
+# IfcIO
+
+**IfcIO** is a fast, 100% managed .NET library for building, reading, and exporting **Industry Foundation Classes** (`.ifc`) files compliant with **IFC2x3 Coordination View V2.0** and **IFC4 Design Transfer / Reference View** without third-party dependencies or native code.
+
+Built clean-room under the [IOExtend](https://github.com/IOExtend) organization as the shared open-standards IFC foundation for AEC/BIM projects (including [NwcIO](https://github.com/IOExtend/NwcIO) and [RvtIO](https://github.com/IOExtend/RvtIO)).
+
+## Key Features
+
+- **Full Model Ingestion & Export (`IfcModel`)**:
+  - Reconstruct complete spatial hierarchy (Project, Site, Building, Storeys), elements, properties, materials, and 3D meshes from any `.ifc` or `.ifczip` file.
+  - Multi-line STEP statement accumulation and quote-aware tokenization in `StepReader` and high-throughput streaming in `StepWriter`.
+- **IFC4 Modern Mesh Tessellation (`IfcTriangulatedFaceSet`)**:
+  - Encodes geometry using compact `IfcTriangulatedFaceSet` and `IfcCartesianPointList3D` under representation type `'Tessellation'` for IFC4 exports (>60% smaller file sizes than legacy faceted B-Rep).
+- **Direct 3D Exporters (glTF 2.0 & Wavefront OBJ)**:
+  - Instant conversion of any IFC model to binary glTF 2.0 (`.glb`) with PBR metallic-roughness materials and vertex normals, or Wavefront OBJ (`.obj` + `.mtl`).
+- **PKZip Compressed IFC (`.ifczip`)**:
+  - Built-in transparent compression and decompression for standard `.ifczip` archives with zero native dependencies.
+- **Cross-Platform CLI Tool (`ifcio`)**:
+  - Global .NET CLI tool (`IfcIO.Cli` on NuGet) providing `info`, `export`, `pack`, `unpack`, `clash`, `diff`, `view`, and `validate` commands.
+- **buildingSMART 22-Character GlobalId (`IfcGuid`)**:
+  - Standard base64-like buildingSMART encoding (`0-9, A-Z, a-z, _, $`). Bidirectional conversion between 128-bit `.NET Guid` and 22-character IFC GlobalId.
+- **3D Geometric Clash Detection & Revision Diff**:
+  - Built-in Möller triangle collision, proximity clustering, structural grid location assignment, revision comparison, and buildingSMART BCF 2.1 zip reporting.
+
+The library targets .NET 8 and .NET 10, uses 100% pure managed code with zero native dependencies, and supports Windows, Linux, and macOS.
+
+## Where to go next
+
+- [Getting started](getting-started.md): install the package or CLI tool and run a first export or model query.
+- [Public API](public-api.md): supported surface and key entry points of the library.
+- [API reference](api/IfcIO.yml): complete API documentation generated directly from XML source docstrings.
+- [Source on GitHub](https://github.com/IOExtend/IfcIO) and [DeepWiki](https://deepwiki.com/IOExtend/IfcIO) for an automated architectural overview of the repository.
+
+IfcIO is licensed under the MIT License and is an independent implementation of the ISO 10303-21 STEP and buildingSMART specifications. buildingSMART and IFC are registered trademarks of buildingSMART International Ltd.

docs/public-api.md

@@ -0,0 +1,44 @@
+---
+title: Public API
+---
+
+# Public API Surface
+
+The `IfcIO` package is the supported surface listed here.
+
+## Core Model & Hierarchy
+
+| Type | Description |
+|---|---|
+| `IfcModel` | Central model container managing spatial hierarchy (Project, Site, Building, Storey), elements, materials, property sets, and geometry representations. Opens and writes `.ifc` and `.ifczip` files. |
+| `IfcElement` | Base BIM product element representing walls, slabs, columns, beams, doors, windows, pipes, ducts, and generic components. |
+| `IfcStorey`, `IfcBuilding`, `IfcSite`, `IfcProject` | Spatial structure hierarchy components with coordinates, elevations, and relationships. |
+| `IfcGuid` | buildingSMART 22-character compressed GlobalId encoder/decoder with bidirectional conversion to 128-bit .NET `Guid`. |
+
+## Geometry & Representation
+
+| Type | Description |
+|---|---|
+| `IfcMeshGeometry` | 3D polygonal triangle mesh data structure holding double-precision vertices, normals, and face index buffers. |
+| `IfcTriangulatedFaceSet` | Modern IFC4 compact tessellation geometry generator (`IfcCartesianPointList3D`). |
+| `IfcFacetedBrep` | Standard IFC2x3 faceted boundary representation (`IfcClosedShell`, `IfcFace`, `IfcPolyLoop`). |
+| `IfcProfileDef` | 2D parametric profile definitions (rectangle, circle, I-shape, L-shape, composite). |
+
+## Import & Export
+
+| Type | Description |
+|---|---|
+| `StepReader` | Low-level ISO 10303-21 STEP physical file parser supporting multi-line statements and quote escapes. |
+| `StepWriter` | High-throughput ISO 10303-21 STEP physical file serializer. |
+| `IfcGlbExporter` | Binary glTF 2.0 exporter generating specification-compliant `.glb` files with PBR materials. |
+| `IfcObjExporter` | Wavefront OBJ geometry exporter with MTL material library generation. |
+| `IfcZipArchive` | Pure managed PKZip container compression and decompression for `.ifczip` files. |
+
+## Coordination & Validation
+
+| Type | Description |
+|---|---|
+| `IfcClashDetector` | Broad-phase spatial index and narrow-phase Möller triangle collision engine for IFC models. |
+| `IfcDiffEngine` | Revision comparison engine detecting added, deleted, and modified IFC elements and geometry shifts. |
+| `IfcValidator` | Structural STEP syntax and buildingSMART schema conformance validator. |
+| `IfcBcfExporter` | buildingSMART BIM Collaboration Format (BCF 2.1 `.bcfzip`) issue and viewpoint generator. |

docs/toc.yml

@@ -0,0 +1,13 @@
+- name: Getting started
+  href: getting-started.md
+- name: Guides
+  href: public-api.md
+  items:
+    - name: Public API
+      href: public-api.md
+- name: API reference
+  href: api/
+- name: GitHub
+  href: https://github.com/IOExtend/IfcIO
+- name: DeepWiki
+  href: https://deepwiki.com/IOExtend/IfcIO