add docs

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Publish docs via GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    tags:
+      - "v*"
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy development docs
+        if: github.ref_type == 'branch'
+        run: |
+          cd docs
+          mike deploy --push --update-aliases dev latest
+          mike set-default --push latest
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Deploy release docs
+        if: github.ref_type == 'tag'
+        run: |
+          cd docs
+          VERSION="${GITHUB_REF_NAME#v}"
+          mike deploy --push --update-aliases "$VERSION" latest
+          mike set-default --push latest
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.pre-commit-config.yaml

@@ -11,6 +11,7 @@ repos:
     hooks:
       - id: trailing-whitespace
       - id: check-yaml
+        args: ["--unsafe"]
       - id: end-of-file-fixer
       - id: requirements-txt-fixer
       - id: check-merge-conflict
@@ -36,6 +37,7 @@ repos:
         exclude: >
           (?x)^(
               (?:.*/)?docs/imgs/.*|
+              (?:.*/)?docs/src/assets/images/.*|
               .*/json\.hpp|
               .*/pybind_json\.hpp
           )$

NanoCtrl/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nanoctrl"
-version = "0.0.8"
+version = "0.1.0"
 edition = "2021"
 description = "NanoInfra control plane server"
 license = "MIT"

NanoCtrl/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "nanoctrl"
-version = "0.0.8"
+version = "0.1.0"
 description = "Shared NanoCtrl lifecycle client for NanoInfra services"
 requires-python = ">=3.10"
 dependencies = ["httpx>=0.24"]

README.md

@@ -2,6 +2,7 @@
   <img src="docs/imgs/assets/logo.png" alt="DLSlime logo" width="44%">
 </div>
 <p align="center">
+  <a href="docs/README.md">Docs</a> |
   <a href="docs/roadmap.md"><img src="docs/imgs/assets/roadmap.svg" width="16" height="16" style="vertical-align: middle;"> Roadmap </a> |
   <a href="https://join.slack.com/t/dlslime/shared_invite/zt-3e9zvercw-a89KI_Ig8N1UTaol_q6MXg"><img src="docs/imgs/assets/slack.svg" width="16" height="16" style="vertical-align: middle;"> Slack </a> |
   <a href="docs/imgs/assets/wechat_qrcode.jpg"><img src="docs/imgs/assets/wechat.svg" width="16" height="16" style="vertical-align: middle;"> WeChat Group </a> |

README_zh.md

@@ -2,6 +2,7 @@
   <img src="docs/imgs/assets/logo.png" alt="DLSlime logo" width="44%">
 </div>
 <p align="center">
+  <a href="docs/README.md">文档</a> |
   <a href="docs/roadmap.md"><img src="docs/imgs/assets/roadmap.svg" width="16" height="16" style="vertical-align: middle;"> 路线图 </a> |
   <a href="https://join.slack.com/t/dlslime/shared_invite/zt-3e9zvercw-a89KI_Ig8N1UTaol_q6MXg"><img src="docs/imgs/assets/slack.svg" width="16" height="16" style="vertical-align: middle;"> Slack </a> |
   <a href="docs/imgs/assets/wechat_qrcode.jpg"><img src="docs/imgs/assets/wechat.svg" width="16" height="16" style="vertical-align: middle;"> 微信群 </a> |

docs/Makefile

@@ -0,0 +1,53 @@
+.PHONY: help serve serve-dirty serve-versioned build clean install check-links deploy-dev deploy-version set-default
+
+PYTHON ?= python
+MKDOCS ?= $(shell command -v uv >/dev/null 2>&1 && echo uv run mkdocs || echo mkdocs)
+MIKE ?= $(shell command -v uv >/dev/null 2>&1 && echo uv run mike || echo mike)
+LINKCHECK ?= $(shell command -v uv >/dev/null 2>&1 && echo uv run mkdocs-linkcheck || echo mkdocs-linkcheck)
+
+help:
+	@echo "Available commands:"
+	@echo "  make serve        - Serve documentation locally"
+	@echo "  make serve-dirty  - Serve with --dirtyreload"
+	@echo "  make serve-versioned - Serve versioned docs from the local gh-pages branch"
+	@echo "  make build        - Build the static documentation site"
+	@echo "  make check-links  - Check documentation links"
+	@echo "  make deploy-dev   - Build versioned docs locally into gh-pages branch as dev/latest"
+	@echo "  make deploy-version VERSION=x.y.z - Build a release docs version"
+	@echo "  make clean        - Remove generated documentation artifacts"
+
+serve:
+	$(MKDOCS) serve
+
+serve-dirty:
+	$(MKDOCS) serve --dirtyreload
+
+serve-versioned:
+	$(MIKE) serve --config-file mkdocs.local.yml --dev-addr 0.0.0.0:18080
+
+build:
+	$(MKDOCS) build
+
+install:
+	python -m pip install -r requirements.txt
+
+check-links:
+	$(LINKCHECK) src
+
+deploy-dev:
+	$(MIKE) deploy --config-file mkdocs.local.yml --update-aliases dev latest
+	$(MIKE) set-default latest
+
+deploy-version:
+	test -n "$(VERSION)"
+	$(MIKE) deploy --update-aliases "$(VERSION)" latest
+	$(MIKE) set-default latest
+
+set-default:
+	test -n "$(VERSION)"
+	$(MIKE) set-default "$(VERSION)"
+
+clean:
+	rm -rf site/
+	rm -rf .cache/
+	find . -type d -name "__pycache__" -exec rm -rf {} +

docs/README.md

@@ -1,63 +1,93 @@
 # DLSlime Documentation
 
-This directory collects design notes, benchmark guides, platform docs, and the
-project roadmap. Keep the root README concise; put deeper operational and
-design details here or under `bench/`.
+This directory contains the DLSlime documentation site. The site uses
+MkDocs Material with bilingual English/Chinese pages, explicit navigation, and
+GitHub Pages publishing.
 
-## Quick Links
+## Prerequisites
 
-### Benchmarks
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) for local development, or `pip` for CI-style installs
 
-- [Benchmark directory README](../bench/README.md) - Transfer, endpoint, cache, and RPC benchmark entry point
-- [SlimeRPC Benchmark](benchmark-rpc.md) - Run and interpret the SlimeRPC vs Ray benchmark
+## Quick Start
 
-### Design
+Run these commands from the `docs/` directory:
 
-- [DLSlimeCache](design/dlslime-cache.md) - RDMA cache-service assignment directory
-- [PeerAgent Directed Connections](design/peer-agent-directed-connections.md) - Directed PeerAgent connection management
-- [Control Plane vs Mooncake](design/control-plane-vs-mooncake.md) - Control-plane comparison notes
-- [Endpoint Ownership Model](endpoint-ownership-model.md) - Endpoint memory and completion ownership
-- [Endpoint DeviceSignal Refactor](endpoint-device-signal-refactor.md) - Slot-owned completion hazards in RDMAEndpoint
+```bash
+cd docs
 
-### Platform Support
-
-- [Huawei Ascend](huawei_ascend/README.md) - Ascend Direct integration guide
-
-### Project
+make install
+make serve
+```
 
-- [Roadmap](roadmap.md) - Development roadmap
+Useful commands:
+
+```bash
+make serve        # local preview with live reload
+make serve-dirty  # faster dirty reload if normal reload is slow
+make serve-versioned
+make build        # build static site into docs/site/
+make check-links  # check links under docs/src/
+make deploy-dev   # build versioned docs into gh-pages as dev/latest
+make deploy-version VERSION=0.1.0
+make clean        # remove generated artifacts
+```
 
-## Directory Structure
+## Structure
 
 ```text
 docs/
-├── README.md
-├── benchmark-rpc.md
-├── endpoint-device-signal-refactor.md
-├── endpoint-ownership-model.md
-├── roadmap.md
-├── design/
-│   ├── control-plane-vs-mooncake.md
-│   ├── dlslime-cache.md
-│   └── peer-agent-directed-connections.md
-├── huawei_ascend/
-│   └── README.md
-└── imgs/
-    ├── interface.svg
-    ├── performance.png
-    └── assets/
+├── mkdocs.yml
+├── Makefile
+├── pyproject.toml
+├── requirements.txt
+├── src/
+│   ├── index.md
+│   ├── index.zh.md
+│   ├── installation.md
+│   ├── quickstart.md
+│   ├── guide/
+│   ├── design/
+│   ├── platform/
+│   ├── api_reference.md
+│   └── assets/
+└── imgs/                 # legacy image location used by root README
 ```
 
-## Contributing
+## Translation
+
+The documentation uses suffix-based i18n:
 
-When adding documentation:
+- `page.md` is the English source.
+- `page.zh.md` is the Chinese source.
+- If a Chinese page is missing, MkDocs falls back to the English page.
+
+## Publishing
+
+`.github/workflows/docs.yml` builds and publishes the site to GitHub Pages when
+documentation changes land on `main` or `master`. Branch builds are published as
+`dev` with the `latest` alias. Git tags matching `v*` are published as release
+versions, for example `v0.1.0` becomes version `0.1.0`. The workflow can also be
+run manually from GitHub Actions.
+
+Version switching is powered by
+[mike](https://github.com/jimporter/mike). The local `docs/src/versions.json`
+file is useful for static builds, but a faithful local preview of the dropdown
+uses mike's versioned server:
+
+```bash
+cd docs
+make deploy-dev
+make serve-versioned
+```
 
-1. Put benchmark runbooks under `bench/` unless they are a focused deep dive.
-2. Put architecture and design notes under `docs/design/`.
-3. Update this index and any relevant README.
-4. Keep generated logs, CSVs, and profiler output out of `docs/`.
+`make deploy-dev` uses `mkdocs.local.yml` so local language links point at the
+local `mike serve` root. The GitHub Actions workflow uses `mkdocs.yml`, where
+`site_url` keeps the `/DLSlime/` project-pages prefix. Deployed `versions.json`
+metadata is generated by mike on the `gh-pages` branch.
 
-## See Also
+## Legacy Links
 
-- Main README: [../README.md](../README.md)
-- Chinese README: [../README_zh.md](../README_zh.md)
+Older Markdown files directly under `docs/` are kept for repository links and
+README compatibility. New content should be added under `docs/src/` and wired
+into `docs/mkdocs.yml`.

docs/mkdocs.local.yml

@@ -0,0 +1,3 @@
+INHERIT: mkdocs.yml
+
+site_url: http://127.0.0.1:18080/