doc: make doc testable

.github/workflows/doc.yml

@@ -0,0 +1,68 @@
+name: Docs
+
+on:
+  push:
+    branches: [ "*" ]
+  pull_request:
+    branches: [ "*" ]
+
+jobs:
+  doc_verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          
+      - name: Install embedme
+        run: npm install -g embedme
+        
+      - name: Verify README.md embedded code
+        run: npx embedme --verify README.md
+
+  doc_test:
+    continue-on-error: true
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - macos-latest
+          - ubuntu-24.04
+    runs-on: ${{matrix.os}}
+    steps:
+      - uses: actions/checkout@v4
+        
+      - name: Set up Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: '1.20'
+
+      - name: Install dependencies on macOS
+        if: startsWith(matrix.os, 'macos')
+        run: |
+          set -e
+          set -x
+          source doc/_readme/scripts/install_macos.sh
+
+      - name: Install dependencies on Ubuntu
+        if: startsWith(matrix.os, 'ubuntu')
+        run: |
+          set -e
+          set -x
+          source doc/_readme/scripts/install_ubuntu.sh
+
+      - name: Install llgo
+        run: |
+          set -e
+          set -x
+          source doc/_readme/scripts/install_llgo.sh
+
+      - name: Test doc code blocks
+        run: |
+          set -e
+          set -x
+          source doc/_readme/scripts/run.sh
+

.github/workflows/go.yml

@@ -10,6 +10,22 @@ on:
     branches: [ "*" ]
 
 jobs:
+  fmt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.20'
+
+      - name: Check formatting
+        run: |
+          if [ -n "$(go fmt ./...)" ]; then
+            echo "Some files are not properly formatted. Please run 'go fmt ./...'"
+            exit 1
+          fi
 
   test:
     strategy:

README.md

@@ -47,6 +47,8 @@ You can import a C/C++ standard library in LLGo!
 
 Here is a simple example:
 
+<!-- embedme doc/_readme/llgo_simple/simple.go -->
+
 ```go
 package main
 
@@ -77,6 +79,8 @@ llgo run .
 
 LLGo use `go:linkname` to link an extern symbol througth its ABI:
 
+<!-- embedme doc/_readme/llgo_call_c/call_c.go#L3-L6 -->
+
 ```go
 import _ "unsafe" // for go:linkname
 
@@ -86,6 +90,8 @@ func Sqrt(x float64) float64
 
 You can directly integrate it into [your own code](_demo/linkname/linkname.go):
 
+<!-- embedme doc/_readme/llgo_call_c/call_c.go -->
+
 ```go
 package main
 
@@ -101,6 +107,8 @@ func main() {
 
 Or put it into a package (see [c/math](c/math/math.go)):
 
+<!-- embedme doc/_readme/llgo_call_cmath/call_cmath.go -->
+
 ```go
 package main
 
@@ -135,6 +143,8 @@ Note: For third-party libraries (such as pandas and pytorch), you still need to
 
 Here is an example:
 
+<!-- embedme doc/_readme/llgo_call_py/call_py.go -->
+
 ```go
 package main
 
@@ -152,6 +162,8 @@ func main() {
 
 It is equivalent to the following Python code:
 
+<!-- embedme doc/_readme/llgo_call_py/call_math.py -->
+
 ```py
 import math
 
@@ -163,6 +175,8 @@ Here, We call `py.Float(2)` to create a Python number 2, and pass it to Python
 
 Let's look at a slightly more complex example. For example, we use `numpy` to calculate:
 
+<!-- embedme doc/_readme/llgo_py_list/py_list.go -->
+
 ```go
 package main
 
@@ -340,20 +354,24 @@ Follow these steps to generate the `llgo` command (its usage is the same as the
 
 ### on macOS
 
+<!-- embedme doc/_readme/scripts/install_macos.sh#L2-L1000 -->
+
 ```sh
 brew update
-brew install llvm@18 pkg-config bdw-gc openssl
+brew install llvm@18 pkg-config bdw-gc openssl cjson
 brew install python@3.12 # optional
 go install -v github.com/goplus/llgo/cmd/llgo@latest
 ```
 
 ### on Linux (Debian/Ubuntu)
 
+<!-- embedme doc/_readme/scripts/install_ubuntu.sh#L2-L1000 -->
+
 ```sh
 echo "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs)-18 main" | sudo tee /etc/apt/sources.list.d/llvm.list
 wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
 sudo apt-get update
-sudo apt-get install -y llvm-18-dev clang-18 lld-18 pkg-config libgc-dev libssl-dev zlib1g-dev
+sudo apt-get install -y llvm-18-dev clang-18 libclang-18-dev lld-18 pkg-config libgc-dev libssl-dev zlib1g-dev libcjson-dev python3.12-dev
 sudo apt-get install -y python3.12-dev # optional
 go install -v github.com/goplus/llgo/cmd/llgo@latest
 ```
@@ -373,9 +391,12 @@ TODO
 
 How do I generate these tools?
 
+<!-- embedme doc/_readme/scripts/install_llgo.sh#L2-L1000 -->
+
 ```sh
 git clone https://github.com/goplus/llgo.git
 cd llgo
+go install -v ./cmd/...
 go install -v ./chore/...  # compile all tools except pydump
 cd chore/_xtool
 llgo install ./...   # compile pydump

doc/_readme/llgo_call_c/call_c.go

@@ -0,0 +1,10 @@
+package main
+
+import _ "unsafe" // for go:linkname
+
+//go:linkname Sqrt C.sqrt
+func Sqrt(x float64) float64
+
+func main() {
+	println("sqrt(2) =", Sqrt(2))
+}

doc/_readme/llgo_call_cmath/call_cmath.go

@@ -0,0 +1,7 @@
+package main
+
+import "github.com/goplus/llgo/c/math"
+
+func main() {
+	println("sqrt(2) =", math.Sqrt(2))
+}

doc/_readme/llgo_call_py/call_math.py

@@ -0,0 +1,4 @@
+import math
+
+x = math.sqrt(2)
+print("sqrt =", x)

doc/_readme/llgo_call_py/call_py.go

@@ -0,0 +1,12 @@
+package main
+
+import (
+	"github.com/goplus/llgo/py"
+	"github.com/goplus/llgo/py/math"
+	"github.com/goplus/llgo/py/std"
+)
+
+func main() {
+	x := math.Sqrt(py.Float(2))       // x = sqrt(2)
+	std.Print(py.Str("sqrt(2) ="), x) // print("sqrt(2) =", x)
+}

doc/_readme/llgo_py_list/py_list.go

@@ -0,0 +1,22 @@
+package main
+
+import (
+	"github.com/goplus/llgo/py"
+	"github.com/goplus/llgo/py/numpy"
+	"github.com/goplus/llgo/py/std"
+)
+
+func main() {
+	a := py.List(
+		py.List(1.0, 2.0, 3.0),
+		py.List(4.0, 5.0, 6.0),
+		py.List(7.0, 8.0, 9.0),
+	)
+	b := py.List(
+		py.List(9.0, 8.0, 7.0),
+		py.List(6.0, 5.0, 4.0),
+		py.List(3.0, 2.0, 1.0),
+	)
+	x := numpy.Add(a, b)
+	std.Print(py.Str("a+b ="), x)
+}

doc/_readme/llgo_simple/simple.go

@@ -0,0 +1,7 @@
+package main
+
+import "github.com/goplus/llgo/c"
+
+func main() {
+	c.Printf(c.Str("Hello world\n"))
+}

doc/_readme/scripts/install_llgo.sh

@@ -0,0 +1,8 @@
+# shellcheck disable=all
+git clone https://github.com/goplus/llgo.git
+cd llgo
+go install -v ./cmd/...
+go install -v ./chore/...  # compile all tools except pydump
+cd chore/_xtool
+llgo install ./...   # compile pydump
+go install github.com/goplus/hdq/chore/pysigfetch@v0.8.1  # compile pysigfetch

doc/_readme/scripts/install_macos.sh

@@ -0,0 +1,5 @@
+# shellcheck disable=all
+brew update
+brew install llvm@18 pkg-config bdw-gc openssl cjson
+brew install python@3.12 # optional
+go install -v github.com/goplus/llgo/cmd/llgo@latest

doc/_readme/scripts/install_ubuntu.sh

@@ -0,0 +1,7 @@
+# shellcheck disable=all
+echo "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs)-18 main" | sudo tee /etc/apt/sources.list.d/llvm.list
+wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+sudo apt-get update
+sudo apt-get install -y llvm-18-dev clang-18 libclang-18-dev lld-18 pkg-config libgc-dev libssl-dev zlib1g-dev libcjson-dev python3.12-dev
+sudo apt-get install -y python3.12-dev # optional
+go install -v github.com/goplus/llgo/cmd/llgo@latest

doc/_readme/scripts/run.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+cd ./doc/_readme/ || exit 1
+llgo build -v ./...
+pip3 install --user numpy
+for dir in ./*/; do
+  if grep -q "func main()" "$dir"/*.go 2>/dev/null; then
+    echo "Running examples in $dir"
+    llgo run "$dir"
+  fi
+done