构建文档

安装依赖

文档构建工具已包含在开发依赖中:

	uv sync
	npm install

构建 HTML

	uv run sphinx-build -b html docs docs/_build/html

构建产物在 docs/_build/html/ 目录下, 用浏览器打开 index.html 即可阅读。

构建 PDF

使用 XeLaTeX 编译, 字体为 HarmonyOS Sans SC。

安装 TeX 环境

Ubuntu/Debian:

sudo apt install texlive-xetex texlive-fonts-recommended texlive-latex-extra \
  texlive-lang-chinese latexmk

安装字体

项目仓库已包含 HarmonyOS Sans SC 字体文件 (位于 fonts/ 目录):

	sudo mkdir -p /usr/local/share/fonts/harmonyos
	sudo cp fonts/*.ttf /usr/local/share/fonts/harmonyos/
	sudo fc-cache -f

验证字体可用:

fc-list | grep HarmonyOS

编译 PDF

	uv run sphinx-build -b latex docs docs/_build/latex
	sed -i 's/\\begin{longtable}{ll}/\\begin{longtable}{l p{0.55\\linewidth}}/g' docs/_build/latex/nearlink-sdr.tex
	for f in docs/_build/latex/mermaid-*.pdf; do [ -f "$$f" ] && pdfcrop "$$f" "$$f" >/dev/null 2>&1; done || true
	cd docs/_build/latex && make

生成的 PDF 位于 docs/_build/latex/nearlink-sdr.pdf。

实时预览

开发文档时, 使用 sphinx-autobuild 自动重建并刷新浏览器:

	uv run pip install sphinx-autobuild
	uv run sphinx-autobuild docs docs/_build/html

浏览器访问 http://127.0.0.1:8000。

文档结构

docs/
├── conf.py               # Sphinx 配置
├── index.md              # 首页
├── tutorials/            # 教程 (学习导向)
├── how-to/               # 操作指南 (任务导向)
├── reference/            # 技术参考 (信息导向)
└── explanation/          # 设计说明 (理解导向)

文档使用 MyST Markdown 语法, 详见 MyST 文档。