docs: migrate documentation to MkDocs + Material with auto-generated API reference (#98)

Reorganize docs into MkDocs site with Material theme, auto-generated API
reference from Python docstrings, and GitHub Pages deployment workflow.

- Add mkdocs.yml with Material theme (light/dark toggle, search, tabs)
- Add scripts/gen_ref_pages.py for auto-discovering type_bridge modules
- Add .github/workflows/docs.yml for CI build + GitHub Pages deploy
- Move docs/api/ → docs/guide/ (14 hand-written user guide pages)
- Move docs/{DEVELOPMENT,TESTING,TYPEDB,INTERNALS,ABSTRACT_TYPES}.md → docs/development/
- Create docs/getting-started/ with installation and quickstart guides
- Create docs/index.md landing page
- Add docs dependency group to pyproject.toml
- Update all cross-links in README.md, CLAUDE.md, and moved docs
- Fix missing type annotation on QueryBuilder.match_entity filters param

Author: ds1sqe

.github/workflows/docs.yml

@@ -0,0 +1,86 @@
+name: Documentation
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "type_bridge/**"
+      - "mkdocs.yml"
+      - "scripts/gen_ref_pages.py"
+  pull_request:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "type_bridge/**"
+      - "mkdocs.yml"
+      - "scripts/gen_ref_pages.py"
+  workflow_dispatch:
+
+# Allow only one concurrent deployment
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+# Sets permissions for GitHub Pages deployment
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo registry and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            type-bridge-core/target
+          key: ${{ runner.os }}-cargo-docs-${{ hashFiles('type-bridge-core/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-docs-
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra docs
+
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
+      - name: Upload artifact
+        if: github.ref == 'refs/heads/master' && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.ref == 'refs/heads/master' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -31,6 +31,9 @@ tmp/
 benchmarks/.results/
 .benchmarks/
 
+# MkDocs build output
+site/
+
 # Reference repos
 typeql-ref/
 type-bridge-core/target/

CLAUDE.md

@@ -187,37 +187,39 @@ The project requires:
 
 ## Documentation
 
+Full documentation site: **[https://ds1sqe.github.io/type-bridge/](https://ds1sqe.github.io/type-bridge/)**
+
 ### User Documentation
 
 - **[README.md](README.md)** - Quick start guide for users
 
 ### Development Guides
 
-- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development setup, commands, code quality standards
-- **[docs/TESTING.md](docs/TESTING.md)** - Testing strategy, patterns, and execution
+- **[docs/development/setup.md](docs/development/setup.md)** - Development setup, commands, code quality standards
+- **[docs/development/testing.md](docs/development/testing.md)** - Testing strategy, patterns, and execution
 
 ### TypeDB Integration
 
-- **[docs/TYPEDB.md](docs/TYPEDB.md)** - TypeDB concepts, driver API, TypeQL syntax, 3.x changes
-- **[docs/ABSTRACT_TYPES.md](docs/ABSTRACT_TYPES.md)** - Abstract types and interface hierarchies in TypeDB
+- **[docs/development/typedb.md](docs/development/typedb.md)** - TypeDB concepts, driver API, TypeQL syntax, 3.x changes
+- **[docs/development/abstract-types.md](docs/development/abstract-types.md)** - Abstract types and interface hierarchies in TypeDB
 
 ### Architecture & Internals
 
-- **[docs/INTERNALS.md](docs/INTERNALS.md)** - Internal type system, ModelAttrInfo, modern Python standards
-
-### API Reference
-
-- **[docs/api/README.md](docs/api/README.md)** - API overview and quick reference
-- **[docs/api/attributes.md](docs/api/attributes.md)** - Attribute types and value types
-- **[docs/api/entities.md](docs/api/entities.md)** - Entity definition and ownership
-- **[docs/api/relations.md](docs/api/relations.md)** - Relations, roles, and role players
-- **[docs/api/abstract_types.md](docs/api/abstract_types.md)** - Abstract types implementation and patterns
-- **[docs/api/cardinality.md](docs/api/cardinality.md)** - Card API and Flag system
-- **[docs/api/crud.md](docs/api/crud.md)** - CRUD operations and managers
-- **[docs/api/queries.md](docs/api/queries.md)** - Query expressions and aggregations
-- **[docs/api/schema.md](docs/api/schema.md)** - Schema management and conflict detection
-- **[docs/api/generator.md](docs/api/generator.md)** - Code generator (TQL → Python)
-- **[docs/api/validation.md](docs/api/validation.md)** - Pydantic integration and type safety
+- **[docs/development/internals.md](docs/development/internals.md)** - Internal type system, ModelAttrInfo, modern Python standards
+
+### User Guide (API docs)
+
+- **[docs/guide/index.md](docs/guide/index.md)** - API overview and quick reference
+- **[docs/guide/attributes.md](docs/guide/attributes.md)** - Attribute types and value types
+- **[docs/guide/entities.md](docs/guide/entities.md)** - Entity definition and ownership
+- **[docs/guide/relations.md](docs/guide/relations.md)** - Relations, roles, and role players
+- **[docs/guide/abstract-types.md](docs/guide/abstract-types.md)** - Abstract types implementation and patterns
+- **[docs/guide/cardinality.md](docs/guide/cardinality.md)** - Card API and Flag system
+- **[docs/guide/crud.md](docs/guide/crud.md)** - CRUD operations and managers
+- **[docs/guide/queries.md](docs/guide/queries.md)** - Query expressions and aggregations
+- **[docs/guide/schema.md](docs/guide/schema.md)** - Schema management and conflict detection
+- **[docs/guide/generator.md](docs/guide/generator.md)** - Code generator (TQL → Python)
+- **[docs/guide/validation.md](docs/guide/validation.md)** - Pydantic integration and type safety
 
 ## Getting Help
 

README.md

@@ -256,31 +256,16 @@ The generator supports:
 - Registry module generation for schema metadata and JSON Schema fragments
 - Both `#` and `//` comment styles
 
-See [docs/api/generator.md](docs/api/generator.md) for full documentation.
+See the [Code Generator guide](https://ds1sqe.github.io/type-bridge/guide/generator/) for full documentation.
 
 ## Documentation
 
-- **[CLAUDE.md](CLAUDE.md)** - Project guidance for development, TypeDB concepts, and quick reference
-- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development setup, commands, and code quality standards
-- **[docs/TESTING.md](docs/TESTING.md)** - Testing strategy, patterns, and execution
-- **[docs/TYPEDB.md](docs/TYPEDB.md)** - TypeDB concepts, driver API, and TypeQL syntax
-- **[docs/ABSTRACT_TYPES.md](docs/ABSTRACT_TYPES.md)** - Abstract types and interface hierarchies in TypeDB
-- **[docs/INTERNALS.md](docs/INTERNALS.md)** - Internal type system and architecture
-- **[docs/SKILL.md](docs/SKILL.md)** - AI assistant skill for using type-bridge (for Claude, GPT, etc.)
-
-### API Reference
-
-- **[docs/api/README.md](docs/api/README.md)** - API overview and quick reference
-- **[docs/api/attributes.md](docs/api/attributes.md)** - Attribute types and value types
-- **[docs/api/entities.md](docs/api/entities.md)** - Entity definition and ownership
-- **[docs/api/relations.md](docs/api/relations.md)** - Relations, roles, and role players
-- **[docs/api/abstract_types.md](docs/api/abstract_types.md)** - Abstract types implementation and patterns
-- **[docs/api/cardinality.md](docs/api/cardinality.md)** - Card API and Flag system
-- **[docs/api/crud.md](docs/api/crud.md)** - CRUD operations and managers
-- **[docs/api/queries.md](docs/api/queries.md)** - Query expressions and aggregations
-- **[docs/api/schema.md](docs/api/schema.md)** - Schema management and conflict detection
-- **[docs/api/generator.md](docs/api/generator.md)** - Code generator (TQL → Python)
-- **[docs/api/validation.md](docs/api/validation.md)** - Pydantic integration and type safety
+**[https://ds1sqe.github.io/type-bridge/](https://ds1sqe.github.io/type-bridge/)** — Full documentation site with user guide, API reference, and development guides.
+
+- [Getting Started](https://ds1sqe.github.io/type-bridge/getting-started/) — Installation and quick start
+- [User Guide](https://ds1sqe.github.io/type-bridge/guide/) — Attributes, entities, relations, CRUD, queries, and more
+- [API Reference](https://ds1sqe.github.io/type-bridge/reference/) — Auto-generated from source docstrings
+- [Development](https://ds1sqe.github.io/type-bridge/development/) — Setup, testing, and internals
 
 ## Pydantic Integration
 

docs/ABSTRACT_TYPES.md docs/development/abstract-types.mddocs/ABSTRACT_TYPES.md renamed to docs/development/abstract-types.md

@@ -9,7 +9,7 @@ This document explains how abstract types, interface hierarchies, and polymorphi
 3. [Abstract Types in TypeDB 3.x vs 2.x](#abstract-types-in-typedb-3x-vs-2x)
 4. [Querying Abstract Types](#querying-abstract-types)
 
-For TypeBridge implementation details, patterns, and known issues, see [docs/api/abstract_types.md](api/abstract_types.md).
+For TypeBridge implementation details, patterns, and known issues, see [docs/guide/abstract-types.md](../guide/abstract-types.md).
 
 ---
 
@@ -177,4 +177,4 @@ For more details on TypeDB concepts, see:
 - [Avoiding Interface Redundancies](https://typedb.com/docs/academy/9-modeling-schemas/9.7-avoiding-interface-redundancies/)
 - [Abstract Contracts](https://typedb.com/docs/academy/9-modeling-schemas/9.8-abstract-contracts/)
 
-For TypeBridge implementation details, see [docs/api/abstract_types.md](api/abstract_types.md).
+For TypeBridge implementation details, see [docs/guide/abstract-types.md](../guide/abstract-types.md).

docs/development/index.md

@@ -0,0 +1,9 @@
+# Development
+
+Guides for contributors and developers working on TypeBridge internals.
+
+- [Development Setup](setup.md) -- Package management, Docker setup, code quality standards
+- [Testing](testing.md) -- Testing strategy, unit tests, integration tests, and patterns
+- [TypeDB Concepts](typedb.md) -- TypeDB type system, driver API, and TypeQL syntax
+- [Abstract Types](abstract-types.md) -- Abstract types and interface hierarchies in TypeDB
+- [Internals](internals.md) -- Internal type system, ModelAttrInfo, and architecture

docs/INTERNALS.md docs/development/internals.mddocs/INTERNALS.md renamed to docs/development/internals.md

@@ -723,6 +723,6 @@ These deprecations provide a cleaner, more consistent API following modern Pytho
 
 ---
 
-For API usage, see [docs/api/](api/).
+For API usage, see the [User Guide](../guide/index.md).
 
-For development guidelines, see [DEVELOPMENT.md](DEVELOPMENT.md).
+For development guidelines, see [setup.md](setup.md).

docs/DEVELOPMENT.md docs/development/setup.mddocs/DEVELOPMENT.md renamed to docs/development/setup.md

@@ -380,7 +380,7 @@ uv run pytest --log-cli-level=DEBUG
 uv run pytest --log-cli-level=DEBUG -k "test_entity_insert"
 ```
 
-For more details on logging configuration, see [docs/api/logging.md](api/logging.md).
+For more details on logging configuration, see [docs/guide/logging.md](../guide/logging.md).
 
 ## Environment Setup
 
@@ -461,8 +461,8 @@ All checks must pass before merging PRs.
 
 ---
 
-For testing specifics, see [TESTING.md](TESTING.md).
+For testing specifics, see [testing.md](testing.md).
 
-For TypeDB integration details, see [TYPEDB.md](TYPEDB.md).
+For TypeDB integration details, see [typedb.md](typedb.md).
 
-For internal architecture, see [INTERNALS.md](INTERNALS.md).
+For internal architecture, see [internals.md](internals.md).

docs/TESTING.md docs/development/testing.mddocs/TESTING.md renamed to docs/development/testing.md

@@ -612,6 +612,6 @@ open htmlcov/index.html  # View coverage report
 
 ---
 
-For development setup, see [DEVELOPMENT.md](DEVELOPMENT.md).
+For development setup, see [setup.md](setup.md).
 
-For TypeDB-specific testing considerations, see [TYPEDB.md](TYPEDB.md).
+For TypeDB-specific testing considerations, see [typedb.md](typedb.md).

docs/TYPEDB.md docs/development/typedb.mddocs/TYPEDB.md renamed to docs/development/typedb.md

@@ -540,8 +540,8 @@ tx.close()
 
 ---
 
-For abstract types and interface hierarchies, see [ABSTRACT_TYPES.md](ABSTRACT_TYPES.md).
+For abstract types and interface hierarchies, see [abstract-types.md](abstract-types.md).
 
-For internal implementation details, see [INTERNALS.md](INTERNALS.md).
+For internal implementation details, see [internals.md](internals.md).
 
-For API reference, see [docs/api/](api/).
+For API reference, see the [User Guide](../guide/index.md).