Skip to content

Commit 8d6ff51

Browse files
authored
Merge pull request #113 from ds1sqe/rust-core
docs: migrate documentation to MkDocs + Material with auto-generated …
2 parents a94a695 + 9390695 commit 8d6ff51

32 files changed

Lines changed: 539 additions & 68 deletions

.github/workflows/docs.yml

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches: [master]
6+
paths:
7+
- "docs/**"
8+
- "type_bridge/**"
9+
- "mkdocs.yml"
10+
- "scripts/gen_ref_pages.py"
11+
pull_request:
12+
branches: [master]
13+
paths:
14+
- "docs/**"
15+
- "type_bridge/**"
16+
- "mkdocs.yml"
17+
- "scripts/gen_ref_pages.py"
18+
workflow_dispatch:
19+
20+
# Allow only one concurrent deployment
21+
concurrency:
22+
group: pages-${{ github.ref }}
23+
cancel-in-progress: true
24+
25+
# Sets permissions for GitHub Pages deployment
26+
permissions:
27+
contents: read
28+
pages: write
29+
id-token: write
30+
31+
jobs:
32+
build:
33+
name: Build docs
34+
runs-on: ubuntu-latest
35+
steps:
36+
- name: Checkout code
37+
uses: actions/checkout@v4
38+
39+
- name: Set up Python
40+
uses: actions/setup-python@v5
41+
with:
42+
python-version: "3.13"
43+
44+
- name: Install Rust toolchain
45+
uses: dtolnay/rust-toolchain@stable
46+
47+
- name: Cache cargo registry and build
48+
uses: actions/cache@v4
49+
with:
50+
path: |
51+
~/.cargo/registry
52+
~/.cargo/git
53+
type-bridge-core/target
54+
key: ${{ runner.os }}-cargo-docs-${{ hashFiles('type-bridge-core/Cargo.lock') }}
55+
restore-keys: |
56+
${{ runner.os }}-cargo-docs-
57+
58+
- name: Install uv
59+
uses: astral-sh/setup-uv@v5
60+
with:
61+
enable-cache: true
62+
63+
- name: Install dependencies
64+
run: uv sync --extra docs
65+
66+
- name: Build documentation
67+
run: uv run mkdocs build --strict
68+
69+
- name: Upload artifact
70+
if: github.ref == 'refs/heads/master' && github.event_name != 'pull_request'
71+
uses: actions/upload-pages-artifact@v3
72+
with:
73+
path: site/
74+
75+
deploy:
76+
name: Deploy to GitHub Pages
77+
if: github.ref == 'refs/heads/master' && github.event_name != 'pull_request'
78+
needs: build
79+
runs-on: ubuntu-latest
80+
environment:
81+
name: github-pages
82+
url: ${{ steps.deployment.outputs.page_url }}
83+
steps:
84+
- name: Deploy to GitHub Pages
85+
id: deployment
86+
uses: actions/deploy-pages@v4

.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,9 @@ tmp/
3131
benchmarks/.results/
3232
.benchmarks/
3333

34+
# MkDocs build output
35+
site/
36+
3437
# Reference repos
3538
typeql-ref/
3639
type-bridge-core/target/

CLAUDE.md

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -187,37 +187,39 @@ The project requires:
187187

188188
## Documentation
189189

190+
Full documentation site: **[https://ds1sqe.github.io/type-bridge/](https://ds1sqe.github.io/type-bridge/)**
191+
190192
### User Documentation
191193

192194
- **[README.md](README.md)** - Quick start guide for users
193195

194196
### Development Guides
195197

196-
- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development setup, commands, code quality standards
197-
- **[docs/TESTING.md](docs/TESTING.md)** - Testing strategy, patterns, and execution
198+
- **[docs/development/setup.md](docs/development/setup.md)** - Development setup, commands, code quality standards
199+
- **[docs/development/testing.md](docs/development/testing.md)** - Testing strategy, patterns, and execution
198200

199201
### TypeDB Integration
200202

201-
- **[docs/TYPEDB.md](docs/TYPEDB.md)** - TypeDB concepts, driver API, TypeQL syntax, 3.x changes
202-
- **[docs/ABSTRACT_TYPES.md](docs/ABSTRACT_TYPES.md)** - Abstract types and interface hierarchies in TypeDB
203+
- **[docs/development/typedb.md](docs/development/typedb.md)** - TypeDB concepts, driver API, TypeQL syntax, 3.x changes
204+
- **[docs/development/abstract-types.md](docs/development/abstract-types.md)** - Abstract types and interface hierarchies in TypeDB
203205

204206
### Architecture & Internals
205207

206-
- **[docs/INTERNALS.md](docs/INTERNALS.md)** - Internal type system, ModelAttrInfo, modern Python standards
207-
208-
### API Reference
209-
210-
- **[docs/api/README.md](docs/api/README.md)** - API overview and quick reference
211-
- **[docs/api/attributes.md](docs/api/attributes.md)** - Attribute types and value types
212-
- **[docs/api/entities.md](docs/api/entities.md)** - Entity definition and ownership
213-
- **[docs/api/relations.md](docs/api/relations.md)** - Relations, roles, and role players
214-
- **[docs/api/abstract_types.md](docs/api/abstract_types.md)** - Abstract types implementation and patterns
215-
- **[docs/api/cardinality.md](docs/api/cardinality.md)** - Card API and Flag system
216-
- **[docs/api/crud.md](docs/api/crud.md)** - CRUD operations and managers
217-
- **[docs/api/queries.md](docs/api/queries.md)** - Query expressions and aggregations
218-
- **[docs/api/schema.md](docs/api/schema.md)** - Schema management and conflict detection
219-
- **[docs/api/generator.md](docs/api/generator.md)** - Code generator (TQL → Python)
220-
- **[docs/api/validation.md](docs/api/validation.md)** - Pydantic integration and type safety
208+
- **[docs/development/internals.md](docs/development/internals.md)** - Internal type system, ModelAttrInfo, modern Python standards
209+
210+
### User Guide (API docs)
211+
212+
- **[docs/guide/index.md](docs/guide/index.md)** - API overview and quick reference
213+
- **[docs/guide/attributes.md](docs/guide/attributes.md)** - Attribute types and value types
214+
- **[docs/guide/entities.md](docs/guide/entities.md)** - Entity definition and ownership
215+
- **[docs/guide/relations.md](docs/guide/relations.md)** - Relations, roles, and role players
216+
- **[docs/guide/abstract-types.md](docs/guide/abstract-types.md)** - Abstract types implementation and patterns
217+
- **[docs/guide/cardinality.md](docs/guide/cardinality.md)** - Card API and Flag system
218+
- **[docs/guide/crud.md](docs/guide/crud.md)** - CRUD operations and managers
219+
- **[docs/guide/queries.md](docs/guide/queries.md)** - Query expressions and aggregations
220+
- **[docs/guide/schema.md](docs/guide/schema.md)** - Schema management and conflict detection
221+
- **[docs/guide/generator.md](docs/guide/generator.md)** - Code generator (TQL → Python)
222+
- **[docs/guide/validation.md](docs/guide/validation.md)** - Pydantic integration and type safety
221223

222224
## Getting Help
223225

README.md

Lines changed: 7 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -256,31 +256,16 @@ The generator supports:
256256
- Registry module generation for schema metadata and JSON Schema fragments
257257
- Both `#` and `//` comment styles
258258

259-
See [docs/api/generator.md](docs/api/generator.md) for full documentation.
259+
See the [Code Generator guide](https://ds1sqe.github.io/type-bridge/guide/generator/) for full documentation.
260260

261261
## Documentation
262262

263-
- **[CLAUDE.md](CLAUDE.md)** - Project guidance for development, TypeDB concepts, and quick reference
264-
- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development setup, commands, and code quality standards
265-
- **[docs/TESTING.md](docs/TESTING.md)** - Testing strategy, patterns, and execution
266-
- **[docs/TYPEDB.md](docs/TYPEDB.md)** - TypeDB concepts, driver API, and TypeQL syntax
267-
- **[docs/ABSTRACT_TYPES.md](docs/ABSTRACT_TYPES.md)** - Abstract types and interface hierarchies in TypeDB
268-
- **[docs/INTERNALS.md](docs/INTERNALS.md)** - Internal type system and architecture
269-
- **[docs/SKILL.md](docs/SKILL.md)** - AI assistant skill for using type-bridge (for Claude, GPT, etc.)
270-
271-
### API Reference
272-
273-
- **[docs/api/README.md](docs/api/README.md)** - API overview and quick reference
274-
- **[docs/api/attributes.md](docs/api/attributes.md)** - Attribute types and value types
275-
- **[docs/api/entities.md](docs/api/entities.md)** - Entity definition and ownership
276-
- **[docs/api/relations.md](docs/api/relations.md)** - Relations, roles, and role players
277-
- **[docs/api/abstract_types.md](docs/api/abstract_types.md)** - Abstract types implementation and patterns
278-
- **[docs/api/cardinality.md](docs/api/cardinality.md)** - Card API and Flag system
279-
- **[docs/api/crud.md](docs/api/crud.md)** - CRUD operations and managers
280-
- **[docs/api/queries.md](docs/api/queries.md)** - Query expressions and aggregations
281-
- **[docs/api/schema.md](docs/api/schema.md)** - Schema management and conflict detection
282-
- **[docs/api/generator.md](docs/api/generator.md)** - Code generator (TQL → Python)
283-
- **[docs/api/validation.md](docs/api/validation.md)** - Pydantic integration and type safety
263+
**[https://ds1sqe.github.io/type-bridge/](https://ds1sqe.github.io/type-bridge/)** — Full documentation site with user guide, API reference, and development guides.
264+
265+
- [Getting Started](https://ds1sqe.github.io/type-bridge/getting-started/) — Installation and quick start
266+
- [User Guide](https://ds1sqe.github.io/type-bridge/guide/) — Attributes, entities, relations, CRUD, queries, and more
267+
- [API Reference](https://ds1sqe.github.io/type-bridge/reference/) — Auto-generated from source docstrings
268+
- [Development](https://ds1sqe.github.io/type-bridge/development/) — Setup, testing, and internals
284269

285270
## Pydantic Integration
286271

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ This document explains how abstract types, interface hierarchies, and polymorphi
99
3. [Abstract Types in TypeDB 3.x vs 2.x](#abstract-types-in-typedb-3x-vs-2x)
1010
4. [Querying Abstract Types](#querying-abstract-types)
1111

12-
For TypeBridge implementation details, patterns, and known issues, see [docs/api/abstract_types.md](api/abstract_types.md).
12+
For TypeBridge implementation details, patterns, and known issues, see [docs/guide/abstract-types.md](../guide/abstract-types.md).
1313

1414
---
1515

@@ -177,4 +177,4 @@ For more details on TypeDB concepts, see:
177177
- [Avoiding Interface Redundancies](https://typedb.com/docs/academy/9-modeling-schemas/9.7-avoiding-interface-redundancies/)
178178
- [Abstract Contracts](https://typedb.com/docs/academy/9-modeling-schemas/9.8-abstract-contracts/)
179179

180-
For TypeBridge implementation details, see [docs/api/abstract_types.md](api/abstract_types.md).
180+
For TypeBridge implementation details, see [docs/guide/abstract-types.md](../guide/abstract-types.md).

docs/development/index.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Development
2+
3+
Guides for contributors and developers working on TypeBridge internals.
4+
5+
- [Development Setup](setup.md) -- Package management, Docker setup, code quality standards
6+
- [Testing](testing.md) -- Testing strategy, unit tests, integration tests, and patterns
7+
- [TypeDB Concepts](typedb.md) -- TypeDB type system, driver API, and TypeQL syntax
8+
- [Abstract Types](abstract-types.md) -- Abstract types and interface hierarchies in TypeDB
9+
- [Internals](internals.md) -- Internal type system, ModelAttrInfo, and architecture
Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -723,6 +723,6 @@ These deprecations provide a cleaner, more consistent API following modern Pytho
723723

724724
---
725725

726-
For API usage, see [docs/api/](api/).
726+
For API usage, see the [User Guide](../guide/index.md).
727727

728-
For development guidelines, see [DEVELOPMENT.md](DEVELOPMENT.md).
728+
For development guidelines, see [setup.md](setup.md).
Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -380,7 +380,7 @@ uv run pytest --log-cli-level=DEBUG
380380
uv run pytest --log-cli-level=DEBUG -k "test_entity_insert"
381381
```
382382

383-
For more details on logging configuration, see [docs/api/logging.md](api/logging.md).
383+
For more details on logging configuration, see [docs/guide/logging.md](../guide/logging.md).
384384

385385
## Environment Setup
386386

@@ -461,8 +461,8 @@ All checks must pass before merging PRs.
461461

462462
---
463463

464-
For testing specifics, see [TESTING.md](TESTING.md).
464+
For testing specifics, see [testing.md](testing.md).
465465

466-
For TypeDB integration details, see [TYPEDB.md](TYPEDB.md).
466+
For TypeDB integration details, see [typedb.md](typedb.md).
467467

468-
For internal architecture, see [INTERNALS.md](INTERNALS.md).
468+
For internal architecture, see [internals.md](internals.md).
Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -612,6 +612,6 @@ open htmlcov/index.html # View coverage report
612612

613613
---
614614

615-
For development setup, see [DEVELOPMENT.md](DEVELOPMENT.md).
615+
For development setup, see [setup.md](setup.md).
616616

617-
For TypeDB-specific testing considerations, see [TYPEDB.md](TYPEDB.md).
617+
For TypeDB-specific testing considerations, see [typedb.md](typedb.md).

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -540,8 +540,8 @@ tx.close()
540540

541541
---
542542

543-
For abstract types and interface hierarchies, see [ABSTRACT_TYPES.md](ABSTRACT_TYPES.md).
543+
For abstract types and interface hierarchies, see [abstract-types.md](abstract-types.md).
544544

545-
For internal implementation details, see [INTERNALS.md](INTERNALS.md).
545+
For internal implementation details, see [internals.md](internals.md).
546546

547-
For API reference, see [docs/api/](api/).
547+
For API reference, see the [User Guide](../guide/index.md).

0 commit comments

Comments
 (0)