Skip to content

Commit 4cd7833

Browse files
thirtytwobitsthirtytwobits
committed
Adding mkdocs
1 parent d097499 commit 4cd7833

31 files changed

Lines changed: 822 additions & 1 deletion

‎.github/workflows/docs.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches: ["main"]
6+
paths:
7+
- "docs/**"
8+
- "mkdocs.yml"
9+
- "README.md"
10+
- "DESIGN.md"
11+
- "CONTRIBUTING.md"
12+
- ".github/workflows/docs.yml"
13+
workflow_dispatch:
14+
15+
permissions:
16+
contents: read
17+
pages: write
18+
id-token: write
19+
20+
concurrency:
21+
group: "docs"
22+
cancel-in-progress: true
23+
24+
jobs:
25+
build:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v4
30+
31+
- name: Setup Python
32+
uses: actions/setup-python@v5
33+
with:
34+
python-version: "3.11"
35+
36+
- name: Configure Pages
37+
uses: actions/configure-pages@v5
38+
39+
- name: Install docs dependencies
40+
run: |
41+
python -m pip install --upgrade pip
42+
pip install -r docs/requirements.txt
43+
44+
- name: Build docs site
45+
run: mkdocs build --strict
46+
47+
- name: Upload Pages artifact
48+
uses: actions/upload-pages-artifact@v3
49+
with:
50+
path: site
51+
52+
deploy:
53+
if: github.ref == 'refs/heads/main'
54+
needs: build
55+
runs-on: ubuntu-latest
56+
environment:
57+
name: github-pages
58+
url: ${{ steps.deployment.outputs.page_url }}
59+
steps:
60+
- name: Deploy to GitHub Pages
61+
id: deployment
62+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ __pycache__/
2828
*.pyd
2929
.python-version
3030
.venv/
31+
.venv-docs/
3132
venv/
3233
.pytest_cache/
3334
.mypy_cache/
@@ -46,3 +47,6 @@ nunavut_out
4647

4748
#dsdlc
4849
dsdl_out
50+
51+
# MkDocs output
52+
site/

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ Required:
3939
Common optional tools (enable more checks/lanes):
4040

4141
- Python 3
42-
- `llvm-lit` or `lit` Python module
42+
- `llvm-lit` or `lit` Python module. LLVM tester
4343
- `clang-format`
4444
- `clang-tidy`
4545
- `include-what-you-use`

‎README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -245,3 +245,24 @@ For build internals, workflows, tests, and contribution standards, use:
245245
- [CONTRIBUTING.md](./CONTRIBUTING.md)
246246
- Runtime semantic-wrapper exception allowlist: [`runtime/semantic_wrapper_allowlist.json`](./runtime/semantic_wrapper_allowlist.json)
247247
- Runtime semantic-wrapper generator: [`tools/runtime/generate_runtime_semantic_wrappers.py`](./tools/runtime/generate_runtime_semantic_wrappers.py)
248+
249+
## User manual (MkDocs)
250+
251+
This repository ships a MkDocs + Material documentation site under [`docs/`](./docs).
252+
253+
Local preview:
254+
255+
```bash
256+
python -m pip install -r docs/requirements.txt
257+
mkdocs serve
258+
```
259+
260+
Build the static site:
261+
262+
```bash
263+
mkdocs build --strict
264+
```
265+
266+
GitHub Pages deployment is handled by:
267+
268+
- [`.github/workflows/docs.yml`](./.github/workflows/docs.yml)

‎docs/PAGE_MAP.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Page Map
2+
3+
This manual is organized for three reader paths: users, backend integrators, and contributors.
4+
5+
## Information architecture
6+
7+
1. Home
8+
2. Getting Started
9+
3. CLI
10+
4. Backends
11+
5. Design
12+
6. Validation
13+
7. LSP Guides
14+
8. Development
15+
9. Project map
16+
17+
## Navigation map
18+
19+
- Home
20+
- `index.md`
21+
- Getting Started
22+
- `getting-started/install.md`
23+
- `getting-started/quickstart.md`
24+
- CLI
25+
- `cli/dsdlc.md`
26+
- `cli/dsdl-opt.md`
27+
- `cli/dsdld.md`
28+
- Backends
29+
- `backends/overview.md`
30+
- `backends/object.md`
31+
- Design
32+
- `design/architecture.md`
33+
- `design/dialect-contracts.md`
34+
- Validation
35+
- `PARITY_MATRIX.md`
36+
- `MALFORMED_INPUT_CONTRACT_MATRIX.md`
37+
- `CONVERGENCE_SCORECARD.md`
38+
- LSP Guides
39+
- `LSP_AI_OPERATOR_GUIDE.md`
40+
- `LSP_INDEX_SCHEMA.md`
41+
- `LSP_LINT_RULES.md`
42+
- `LSP_LINT_RULE_AUTHORING.md`
43+
- `LSP_RANKING_MODEL.md`
44+
- Development
45+
- `development/contributing.md`
46+
- `development/testing.md`
47+
- Project
48+
- `PAGE_MAP.md`
49+
50+
## Planned growth
51+
52+
- Auto-generated CLI reference snapshot pages from `dsdlc --help`
53+
- Auto-generated MLIR dialect op reference pages
54+
- Versioned documentation when release cadence requires it

‎docs/assets/images/logo.svg‎

Lines changed: 4 additions & 0 deletions
Loading

‎docs/assets/javascripts/extra.js‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
window.addEventListener("load", () => {
2+
if (typeof mermaid === "undefined") {
3+
return;
4+
}
5+
mermaid.initialize({
6+
startOnLoad: true,
7+
theme: "neutral",
8+
securityLevel: "loose",
9+
});
10+
});

‎docs/backends/object.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Object Backend (`-l obj`)
2+
3+
The object backend compiles generated sources into static objects and optional archives.
4+
5+
## Primary flags
6+
7+
- `--target-language obj`
8+
- `--target-endianness <little|big>` (required)
9+
- `--obj-abi-language <c|cpp>` (`c` default)
10+
- `--target-triple <triple>` (optional)
11+
- `--obj-archive-name <name>`
12+
- `--obj-no-archive`
13+
- `--jobs, -j <N>` compile parallelism (auto if omitted)
14+
15+
## ABI lanes
16+
17+
## C lane (`--obj-abi-language c`)
18+
19+
- Stages generated C under `.obj_stage_c`
20+
- Compiles C translation units to `.o`
21+
- Optionally archives into `.a`
22+
23+
## C++ lane (`--obj-abi-language cpp`)
24+
25+
- Uses canonical profile-agnostic C++ ABI types
26+
- Exports C++ ABI symbols plus C-callable shim symbols
27+
- Stages under `.obj_stage_cpp` (including nested C stage)
28+
29+
## Endianness semantics
30+
31+
Wire semantics remain OpenCyphal-compatible. Target endianness controls codegen/legalization strategy, not wire contract semantics.
32+
33+
## Example
34+
35+
```bash
36+
dsdlc --target-language obj path/to/ns \
37+
--obj-abi-language cpp \
38+
--target-endianness little \
39+
--obj-archive-name my_dsdl \
40+
--jobs 12 \
41+
--outdir out/obj
42+
```

‎docs/backends/overview.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Backend Overview
2+
3+
`dsdlc` shares one frontend/semantic pipeline and dispatches to multiple backend emitters.
4+
5+
## Targets
6+
7+
- `c`: C headers + implementation
8+
- `cpp`: C++ model/runtime outputs (`std`, `pmr`, `autosar`)
9+
- `rust`: crate/module output with profile/runtime controls
10+
- `go`: module/package output
11+
- `ts`: typed model + runtime helpers
12+
- `python`: package + runtime loader/specialization
13+
- `obj`: compiled `.o` + optional `.a`
14+
15+
## Shared principles
16+
17+
- One semantic interpretation per DSDL source set
18+
- Contract-validated lowering boundaries
19+
- Deterministic file planning
20+
- Backend parity coverage in CI
21+
22+
## Object code path
23+
24+
The `obj` lane runs executable lowering and emits compiled artifacts via host compiler toolchains.
25+
26+
See [Object Backend](object.md) for endianness, ABI, and artifact details.

‎docs/cli/dsdl-opt.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# `dsdl-opt`
2+
3+
`dsdl-opt` is the pass-driver for the `dsdl` MLIR dialect.
4+
5+
Use it to inspect and transform lowered DSDL IR through specific pass pipelines.
6+
7+
## Typical use
8+
9+
```bash
10+
dsdlc --target-language mlir path/to/ns > input.mlir
11+
dsdl-opt input.mlir -pass-pipeline='builtin.module(lower-dsdl-exec,dsdl-prove-zero-overhead,dsdl-legalize-endianness)'
12+
```
13+
14+
## Why use it
15+
16+
- Debug pass behavior in isolation
17+
- Validate contract attributes across pipeline boundaries
18+
- Build reproducible IR test cases for lit/unit tests
19+
20+
## Related
21+
22+
- [Dialect and Contracts](../design/dialect-contracts.md)
23+
- [Architecture](../design/architecture.md)

0 commit comments

Comments
 (0)