doc: employ mdbook

.github/workflows/gh-pages.yml

@@ -0,0 +1,17 @@
+name: deploy-github-pages
+on: [push]
+jobs:
+  deploy-github-pages:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: cachix/install-nix-action@v23
+      with:
+        nix_path: nixpkgs=channel:nixos-24.05
+    - run: nix-shell --run "make doc -j"
+    - uses: peaceiris/actions-gh-pages@v3
+      if: ${{ github.ref == 'refs/heads/main' }}
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./book
+        force_orphan: true

.gitignore

@@ -16,4 +16,8 @@ sim_build
 # for gtkwave
 *.fst
 *.gtkw
+
+# for docs
 *.py.dot
+*.py.svg
+book

Makefile

@@ -20,6 +20,10 @@ clean:
 ################################################################################
 # doc
 ################################################################################
-doc: ./docs/images/arch.py.dot
+MDs=$(shell find docs/ -name "*.md")
+doc: ./docs/images/arch.py.svg ./docs/images/arch.configure.py.svg $(MDs)
+	mdbook build
 %.py.dot: %.dot.py
 	python3 $<
+%.py.svg: %.py.dot
+	dot -Tsvg $< -o $@

book.toml

@@ -0,0 +1,9 @@
+[book]
+authors = ["xieby1"]
+language = "en"
+multilingual = false
+src = "docs/"
+title = "OpenAIA.scala"
+
+[output.html]
+git-repository-url = "https://github.com/xieby1/OpenAIA.scala"

docs/SUMMARY.md

@@ -0,0 +1,5 @@
+# Summary
+
+# 🏠主页
+
+* [📔OpenAIA.scala](./index.md)

docs/index.md

@@ -0,0 +1,3 @@
+![](./images/arch.py.svg)
+
+![](./images/arch.configure.py.svg)

shell.nix

@@ -38,6 +38,7 @@ in pkgs.mkShell {
     pkgs.zlib
     # for docs
     pkgs.graphviz
+    pkgs.mdbook
   ];
 
   shellHook = let