开源孪创

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

---

文档部署

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

# 只克隆主分支
git clone -b master --single-branch https://github.com/OpenHUTB/doc
# 安装依赖
conda create -n mkdocs python=3.11
conda activate mkdocs
pip install git+https://github.com/OpenHUTB/mkdocs.git
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
# 可编辑（--editable）模式安装，本地修改 mkdocs 代码后，需要重启 mkdocs serve 才会生效
python -m pip install -e .# 或者安装发布模式# python -m pip install . -i http://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com

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

注意：发布自定义 mkdocs 请参考 链接 。

软件发布

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

撰写规范

命名规则

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>**

红色的 警告

**警告：**<font color="#ED2F2F">_ hutb_</font>

公式

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

行内公式

\(...\)

行间公式

$$
a + b = c
$$

链接

鼠标停留在链接上显示提示文字

[正文](链接 "浮现文字")

多媒体展示

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

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

Vscode 内支持 Markdown 自动补全

首先按下Ctrl+Shift+P启动交互指令终端，输入：

> Preferences: Open User Settings (JSON)

打开设置。然后在末尾添加这么一行配置（注意前面一个配置的最后需要补一个逗号,）：

"[markdown]": { // 作用是开启markdown下的snippet功能。vsc默认是禁用的"editor.quickSuggestions": {
"other": true, // 是否开启其他情况的snippet"comments": true, // 是否开启注释下的snippet"strings": true// 是否开启句子的snippet
},
"editor.acceptSuggestionOnEnter": "on"// 允许使用回车键选中snippet，而不仅仅是tab
}

然后，再次按下ctrl+shift+P启动交互指令终端，输入

> snippets: Configure Snippets

输入markdown并点开这个语言模式，应该会自动打开一个叫 markdown.json 的文件

"cpp": {
"prefix": "cpp", // 触发词"body": [ // 补全内容"```c++",
"$1", // 光标停留位置"```"
],
"description": "Add C++ code block"// 注释
},
"python": {
"prefix": "py", // 触发词"body": [ // 补全内容"```python",
"$1", // 光标停留位置"```"
],
"description": "Add Python code block"// 注释
},
"shell": {
"prefix": "sh", // 触发词"body": [ // 补全内容"```shell",
"$1", // 光标停留位置"```"
],
"description": "Add shell code block"// 注释
},
"json": {
"prefix": "json", // 触发词"body": [ // 补全内容"```json",
"$1", // 光标停留位置"```"
],
"description": "Add Json code block"// 注释
},
"text": {
"prefix": "text", // 触发词"body": [ // 补全内容"```text",
"$1", // 光标停留位置"```"
],
"description": "Add text code block"// 注释
},
"span": {
"prefix": "span", // 触发词"body": [ // 补全内容"<span id='$1'></span>"
],
"description": "Add html span code block"// 注释
},
"yml": {
"prefix": "yml", // 触发词"body": [ // 补全内容"```yml",
"$1", // 光标停留位置"```"
],
"description": "Add yml block"// 注释
}

其他

• mkdocs 定制

  修改完 mkdocs 仓库后，使用以下命令进行本地安装：

  pip uninstall mkdocs -y
  cd mkdocs
  python -m pip install .

  由于 Github Action 的 OpenHUTB/actions-mkdocs 需要使用 pip install hutb-doc -i https://pypi.org/simple 进行安装，所以需要先删除 pypi 已发布的包 ，然后再参考 发布自定义mkdocs 发布 hutb-doc。

• 将 deepwiki 页面下载为 markdown 格式

  下载并解压插件 -> 在 Chrome 浏览器中的地址栏中输入chrome://extensions打开开发模式 -> 点击加载未打包的扩展程序，选择刚才下载来的根目录 -> 点击增加的扩展程序的详情按钮启用自动访问deepwiki和固定到工具栏 -> 打开对应的 deepwiki 页面，点击工具栏中的新出现的按钮，选择Download Current Page。

常见问题

• 修改文件后不自动加载更新

  解决：将 click 的版本从 8.3.0 回退到 8.2.1

  pip install --force-reinstall click==8.2.1

  或者使用以下命令启动服务：mkdocs serve --livereload

• 编译文档时报错：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

• 安装完 hutb-doc 后，运行mkdocs serve --livereload报错：ModuleNotFoundError: No module named 'pymdownx'

  解决：

  pip install pymdown-extensions

许可证

此项目依据 MIT 许可证发布。详情请查阅许可证文件。