文档指南

工作流

欢迎对 Autoware 文档的贡献,并且相同的原则 在贡献指南中描述 的调用.可以通过复刻此存储库并提交拉取请求来进行小的、有限的更改,但较大的更改应首先通过 GitHub 讨论与社区和 Autoware 维护者讨论.

小更改的示例包括：

• 修复拼写或语法错误
• 修复损坏的链接
• 对现有的、定义明确的页面进行添加,例如 故障排除 指南.

较大的更改示例包括：

• 添加具有大量详细信息的新页面,例如教程
• 重新组织现有文档结构

风格指南

您应该尽可能多地参考 Google 开发者文档风格指南.建议阅读该指南的 Highlights page,但如果没有,则应注意以下关键点.

• 使用标准美式英语拼写 和标点符号.
• Use sentence case 用于文档标题和章节标题.
• 使用描述性链接文本.
• 写出易于理解和翻译的短句.

技巧

如何预览您的修改

有两种方法可以在文档网站上预览您的修改.

1. 使用 GitHub Actions 工作流程

请按照以下步骤作.

1. 创建对存储库的拉取请求.
2. 从侧边栏添加 deploy-docs 标签(见下图).
3. 等待几分钟, github-actions 机器人将通知拉取请求预览的 URL.

{ width= 800 }

2. 在本地环境中运行 MkDocs 服务器

您可以使用 mkdocs 命令在本地计算机上构建 Autoware 的文档网站,而不是创建 PR. 假设您使用的是 Ubuntu作系统,请运行以下命令以安装所需的库.

python3 -m pip install -U $(curl -fsSL https://raw.githubusercontent.com/autowarefoundation/autoware-github-actions/main/deploy-docs/mkdocs-requirements.txt)

然后,在你的文档目录上运行 mkdocs serve.

cd /PATH/TO/YOUR-autoware-documentation
mkdocs serve

它将启动 MkDocs 服务器.访问 http://127.0.0.1:8000/ 查看网站的预览.