该项目是一款能让用户快速测试 具身人 、无人车 、无人机 感知、规划、控制算法的影视级物理模拟器文档。

1. 安装 python 3.11，使用pip安装mkdocs

# 只克隆主分支
git clone -b master --single-branch https://github.com/OpenHUTB/doc
# 安装依赖
pip install mkdocs -i http://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com
pip install pymdown-extensions  # pymdownx
pip install -r requirements.txt

（可选）安装完成后使用mkdocs --version查看是否安装成功。

2. 在命令行中进入doc目录下，运行：

# 构建文档（根据Markdown文件生成HTML文件）
mkdocs build
# 启动服务
mkdocs serve

然后使用浏览器打开 http://127.0.0.1:8000，查看文档页面能否正常显示。

3. 部署到github（可选，需要仓库的写入权限）：

mkdocs gh-deploy

该命令会自动将相应内容推送到项目的gh-pages分支上，然后在 Github 项目设置中选择好对应 GitPage 的分支，目录选择/(root)（注意不要是/(docs)，然后通过 https://openhutb.github.io/doc/ 访问即可。

使用虚拟环境会出现找不到git的错误，请添加git的环境变量：

set path=%path%;C:\Program Files\Git\cmd\

4. 删除页脚（可选）

• 克隆删除页脚的mkdocs仓库（删除mkdocs/themes/readthedocs /footer.html文件中的页脚内容）：

git clone https://github.com/OpenHUTB/mkdocs.git

安装mkdocs包：

cd mkdocs
python -m pip install . -i http://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com

然后使用新的mkdocs执行步骤1-3。

将源代码、文档、软件等进行发布，具体步骤参考 链接 。

adv_*.md (advise_*.md) : 建议

build_*.md : 源代码构建

tuto_A_*.md (tutorial_asset_*) : 资产教程

tuto_D_*.md (tutorial_development_*) : 开发教程

tuto_E_*.md (tutorial_example_*) : 参考示例

tuto_G_*.md (tutorial_guide_*) : 指南教程

tuto_M_*.md (tutorial_map_*) : 地图教程

• 页面跳转

1. 定义一个锚(id)： <span id="jump"></span> 或 <span id="jump">跳转到的地方</span>
2. 使用markdown语法：[点击跳转](#jump)

灰色底的变量名 variable：

**<font color="#f8805a">variable</font>**

函数名 method ：

**<font color="#7fb800">method</font>**

函数参数名 self：

<font color="#00a6ed">**self**</font>

注意：markdown_extensions:标签内需要加上- mdx_math（python环境需要安装依赖python-markdown-math）。

行内公式

\(...\)

行间公式

$$
a + b = c
$$

常见图的绘制请参考绘图指南 。

文档页面显示支持 Latex 公式 、视频播放 。

• 编译文档时报错：ERROR - Config value: ‘plugins‘. Error: The “redirects“ plugin is not installed

解决 ：

pip install redirects

• 编译文档时报错：Config value: 'markdown_extensions'. Error: Failed loading extension "mdx_gh_links".

解决：手动安装库 ：

pip install mdx_gh_links

• 克隆仓库时报错：fatal: fetch-pack: invalid index-pack output

解决：

# 设置下载缓存参数
git config --global http.postBuffer 2G
# 确认参数是否正确设置
git config http.postBuffer