Skip to content

Latest commit

 

History

History
319 lines (253 loc) · 10.3 KB

README.md

File metadata and controls

319 lines (253 loc) · 10.3 KB

开源孪创

Continuous Integration Badge Releases Badge License Badge Supported Platforms Badge ZenHub Badge ZenHub Badge ZenHub Badge

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


文档部署

  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查看是否安装成功。

  1. 在命令行中进入doc目录下,运行:
# 构建文档(根据Markdown文件生成HTML文件)
# mkdocs build
# 启动服务
mkdocs serve

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

  1. 部署到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\
  1. 删除页脚(可选)
  • 克隆删除页脚的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 许可证发布。详情请查阅许可证文件。