Skip to content

Commit f1d12e4

Browse files
dcharlot65-openiedcharlot65-openie
committed
Phase 5 + Phase 6: docs scaffold + quality CI
Phase 5 (docs/): - mdBook scaffold with book.toml + SUMMARY.md - Skeleton chapters: introduction, install, hello, tutorial, reference, cookbook, design/why, design/ecosystem - .github/workflows/docs.yml: builds mdBook on push to docs/**, deploys to GitHub Pages at openie-dev.github.io/flow-g Phase 6 (quality): - .github/workflows/quality.yml: cargo fmt/clippy/build on the stub, cargo-audit (weekly + on push), license consistency check - .github/dependabot.yml: weekly cargo + GH actions update PRs - README badges: Release, Quality, Docs, crates.io version, License The docs workflow needs Pages to be enabled in repo settings (Settings → Pages → Source: GitHub Actions).
1 parent 9792e71 commit f1d12e4

14 files changed

Lines changed: 312 additions & 0 deletions

File tree

‎.github/dependabot.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: "github-actions"
4+
directory: "/"
5+
schedule:
6+
interval: "weekly"
7+
open-pull-requests-limit: 5
8+
9+
- package-ecosystem: "cargo"
10+
directory: "/stubs"
11+
schedule:
12+
interval: "weekly"
13+
open-pull-requests-limit: 3

‎.github/workflows/docs.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
- '.github/workflows/docs.yml'
9+
workflow_dispatch:
10+
11+
permissions:
12+
contents: read
13+
pages: write
14+
id-token: write
15+
16+
concurrency:
17+
group: pages
18+
cancel-in-progress: false
19+
20+
jobs:
21+
build:
22+
runs-on: ubuntu-latest
23+
steps:
24+
- uses: actions/checkout@v4
25+
26+
- name: Install mdBook
27+
run: |
28+
curl -fsSL -o mdbook.tar.gz \
29+
https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz
30+
tar -xzf mdbook.tar.gz
31+
chmod +x mdbook
32+
sudo mv mdbook /usr/local/bin/
33+
34+
- name: Build book
35+
run: |
36+
cd docs
37+
mdbook build
38+
39+
- name: Upload artifact
40+
uses: actions/upload-pages-artifact@v3
41+
with:
42+
path: docs/book
43+
44+
deploy:
45+
needs: build
46+
runs-on: ubuntu-latest
47+
environment:
48+
name: github-pages
49+
url: ${{ steps.deployment.outputs.page_url }}
50+
steps:
51+
- name: Deploy to GitHub Pages
52+
id: deployment
53+
uses: actions/deploy-pages@v4

‎.github/workflows/quality.yml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
name: Quality
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
schedule:
8+
- cron: '0 6 * * 1' # Mondays 06:00 UTC — pick up new advisories
9+
workflow_dispatch:
10+
11+
jobs:
12+
stub-checks:
13+
name: Stub checks
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- name: Install Rust
19+
uses: dtolnay/rust-toolchain@stable
20+
with:
21+
components: rustfmt, clippy
22+
23+
- name: Find stub directory
24+
id: stub
25+
run: |
26+
DIR=$(find stubs -mindepth 1 -maxdepth 1 -type d | head -1)
27+
echo "dir=$DIR" >> "$GITHUB_OUTPUT"
28+
29+
- name: cargo fmt
30+
if: steps.stub.outputs.dir
31+
working-directory: ${{ steps.stub.outputs.dir }}
32+
run: cargo fmt -- --check
33+
34+
- name: cargo clippy
35+
if: steps.stub.outputs.dir
36+
working-directory: ${{ steps.stub.outputs.dir }}
37+
run: cargo clippy --all-targets -- -D warnings
38+
39+
- name: cargo build
40+
if: steps.stub.outputs.dir
41+
working-directory: ${{ steps.stub.outputs.dir }}
42+
run: cargo build --release
43+
44+
audit:
45+
name: cargo-audit
46+
runs-on: ubuntu-latest
47+
steps:
48+
- uses: actions/checkout@v4
49+
- name: Find stub directory
50+
id: stub
51+
run: |
52+
DIR=$(find stubs -mindepth 1 -maxdepth 1 -type d | head -1)
53+
echo "dir=$DIR" >> "$GITHUB_OUTPUT"
54+
- name: Audit
55+
if: steps.stub.outputs.dir
56+
uses: rustsec/audit-check@v2.0.0
57+
with:
58+
token: ${{ secrets.GITHUB_TOKEN }}
59+
working-directory: ${{ steps.stub.outputs.dir }}
60+
61+
license-consistency:
62+
name: License consistency
63+
runs-on: ubuntu-latest
64+
steps:
65+
- uses: actions/checkout@v4
66+
- name: Check license trio is present
67+
run: |
68+
set -e
69+
test -f LICENSE
70+
grep -q "Business Source License 1.1" LICENSE
71+
test -f examples/LICENSE
72+
grep -q "Apache License" examples/LICENSE
73+
echo "license trio (BSL-1.1 root, Apache-2.0 examples) intact"
74+
- name: Check stub Cargo.toml license-file
75+
run: |
76+
set -e
77+
for cargo in stubs/*/Cargo.toml; do
78+
grep -q '^license-file = "LICENSE"' "$cargo" || (echo "$cargo missing license-file"; exit 1)
79+
test -f "$(dirname "$cargo")/LICENSE"
80+
done
81+
echo "stub license-file references valid"

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,13 @@
22

33
**A typed FunctionGraph IR for heterogeneous inference.**
44

5+
[![Release](https://github.com/openIE-dev/flow-g/actions/workflows/release.yml/badge.svg)](https://github.com/openIE-dev/flow-g/actions/workflows/release.yml)
6+
[![Quality](https://github.com/openIE-dev/flow-g/actions/workflows/quality.yml/badge.svg)](https://github.com/openIE-dev/flow-g/actions/workflows/quality.yml)
7+
[![Docs](https://github.com/openIE-dev/flow-g/actions/workflows/docs.yml/badge.svg)](https://openie-dev.github.io/flow-g)
8+
[![crates.io](https://img.shields.io/crates/v/flowg.svg)](https://crates.io/crates/flowg)
9+
[![License](https://img.shields.io/badge/license-BSL--1.1-blue.svg)](./LICENSE)
10+
11+
512
flowG is the compiler IR + runtime substrate behind the openIE-dev ecosystem. It takes typed function graphs and dispatches them across CPU, Apple-silicon Metal, WGPU, AMX, and the OpDispatch backend family — with picojoule-budgeted per-op energy measurement built in.
613

714
This is the **public release surface**. Source is private at [`openIE-dev/flow-g-core`](https://github.com/openIE-dev/flow-g-core) — 99 crates spanning the IR, codegen passes, OpDispatch leaves, model runtimes, and benchmarks.

‎docs/book.toml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[book]
2+
title = "flowG"
3+
authors = ["David Charlot <david@openie.dev>"]
4+
description = "The flowG FunctionGraph IR — types, codegen, runtime, OpDispatch backends, energy receipts."
5+
language = "en"
6+
multilingual = false
7+
src = "src"
8+
9+
[output.html]
10+
default-theme = "navy"
11+
preferred-dark-theme = "navy"
12+
git-repository-url = "https://github.com/openIE-dev/flow-g"
13+
git-repository-icon = "fa-github"
14+
edit-url-template = "https://github.com/openIE-dev/flow-g/edit/main/docs/{path}"
15+
site-url = "/flow-g/"
16+
17+
[output.html.search]
18+
enable = true
19+
20+
[output.html.fold]
21+
enable = true

‎docs/src/SUMMARY.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Summary
2+
3+
[Introduction](./introduction.md)
4+
5+
# Getting Started
6+
7+
- [Install](./install.md)
8+
- [Hello, flowG](./hello.md)
9+
10+
# Tutorial
11+
12+
- [Tutorial overview](./tutorial/index.md)
13+
14+
# Reference
15+
16+
- [Reference overview](./reference/index.md)
17+
18+
# Cookbook
19+
20+
- [Recipes](./cookbook/index.md)
21+
22+
# Design
23+
24+
- [Why flowG](./design/why.md)
25+
- [How it fits the openIE ecosystem](./design/ecosystem.md)

‎docs/src/cookbook/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Cookbook
2+
3+
Task-oriented recipes.
4+
5+
*Cookbook recipes coming with v0.2.0.*

‎docs/src/design/ecosystem.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# How flowG fits the openIE ecosystem
2+
3+
Five public projects share a common substrate:
4+
5+
```
6+
lux-lang jmax joule-lang
7+
\ | /
8+
\ | /
9+
▼ ▼ ▼
10+
flow-g ← ← ← jouledb (metered persistence)
11+
▲
12+
│
13+
substrate-energy
14+
(joules)
15+
```
16+
17+
[Detailed design discussion in v0.2.0 docs.]

‎docs/src/design/why.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Why flowG
2+
3+
flowG exists because [reasoning forthcoming with v0.2.0 docs].
4+
5+
## Position in the openIE-dev ecosystem
6+
7+
See [How it fits](./ecosystem.md).

‎docs/src/hello.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Hello, flowG
2+
3+
The minimum example. See the source in [examples/hello/](https://github.com/openIE-dev/flow-g/tree/main/examples/hello).
4+
5+
For a richer walkthrough, see [the tutorial](./tutorial/index.md).

0 commit comments

Comments
 (0)