投稿指南

我们非常欢迎您为 PX4 用户指南做出贡献，无论是简单的拼写和语法修正，还是创建全新的章节都可以。

本主题将介绍如何进行更改并进行测试，文末还附有基本的风格指南。

TIP

注意 您需要一个（免费的）GitHub 账户才能为指南做出贡献。

快速更改

对 现有内容 进行简单更改时，可点击每页底部的 在 GitHub 上编辑 链接（点击后会在 GitHub 上打开该页面以便编辑）。

本指南使用 Gitbook 工具链。更改请求可以通过以下两种方式完成：一是在 Gitbook 网站上使用 Gitbook 编辑器；二是在本地进行（这种方式更灵活，但用户体验稍差）。

1. 打开页面。
2. 点击页面内容下方的 在 GitHub 上编辑 链接。
3. 在页面底部，系统会提示您创建一个单独的分支，然后引导您提交一个 拉取请求。
4. 在 GitHub 页面编辑器下方，您会被提示创建一个单独的分支，然后引导您提交一个 拉取请求。

文档团队会审核您的请求，要么将其合并，要么与您合作进行更新。

添加新内容 - 重大更改

更重大的更改，包括添加新页面或添加/修改图片，在 GitHub 上进行（或进行适当测试）并不容易。对于这类更改，我们建议采用与 代码贡献 相同的方法：

1. 使用 git 工具链将文档源代码下载到本地计算机。
2. 根据需要修改文档（添加、更改、删除）。
3. 使用 Vitepress 测试 文档是否能正确构建。
4. 为了对文档进行大量更改，建议您按以下步骤在本地添加更改，然后创建一个拉取请求：

以下将介绍如何获取源代码、在本地构建（进行测试）以及修改代码。

文件存放位置

本指南使用 旧版 Gitbook 工具链。下面的说明将介绍如何获取 git 并在本地计算机上使用它。

1. 从 https://git-scm.com/downloads 为您的计算机下载 git。
2. 如果您还没有 GitHub 账户，请前往 注册。
3. 在 GitHub 上创建 PX4 用户指南仓库 的副本（复刻）（此处有详细说明）。
4. 将您复刻的仓库克隆（复制）到本地计算机：

   cd ~/wherever/
   git clone https://github.com/<your git name>/PX4-user_guide.git

   例如，若 GitHub 账户名为 "john_citizen" 的用户要克隆 PX4 用户指南的复刻仓库，可以使用以下命令：

   git clone https://github.com/john_citizen/PX4-user_guide.git

5. 进入本地仓库目录：

   cd ~/wherever/PX4-user_guide

6. 添加一个名为 "upstream" 的 远程仓库，指向 PX4 官方版本的仓库：

   git remote add upstream https://github.com/PX4/PX4-user_guide.git

   TIP

   “远程仓库” 是对特定仓库的一种引用。克隆仓库时，默认会创建一个名为 origin 的远程仓库，它指向您复刻的指南仓库。上面的命令创建了一个新的远程仓库 upstream，它指向 PX4 项目的官方文档仓库。

7. 为您的更改创建一个分支：

   git checkout -b <your_feature_branch_name>

   这将在您的计算机上创建一个名为 your_feature_branch_name 的本地分支。
8. 根据需要对文档进行更改（后续章节会提供一般指导）。
9. 当您对更改满意后，可以使用 “提交” 操作将它们添加到本地分支：

   git add <file name>
   git commit -m "<your commit message>"

   关于良好的提交消息规范，请参考 源代码管理 部分。
10. 将本地分支（包括添加到其中的提交）推送到您在 GitHub 上复刻的仓库：

    git push origin your_feature_branch_name

11. 在网页浏览器中访问您在 GitHub 上复刻的仓库，例如：https://github.com/<your git name>/PX4-user_guide.git。在那里，您应该会看到一条消息，表明一个新分支已被推送到您复刻的仓库。
12. 创建一个拉取请求（PR）：
    • 在 “新分支消息” 的右侧（参考上一步），您应该会看到一个绿色按钮，上面写着 “Compare & Create Pull Request”，点击它。
    • 会创建一个拉取请求模板。它会列出您的提交，您可以（必须）添加一个有意义的标题（如果只有一个提交的 PR，通常就是提交消息）和消息（解释您做了什么以及为什么这么做，可参考 其他拉取请求）。
13. 大功告成！PX4 用户指南的维护人员将查看您的贡献，并决定是否将其集成。请不时查看他们是否对您的更改有疑问。

Gitbook 文档工具链

概述：

1. 安装 Vitepress 先决条件：
   • Nodejs 18+
   • Yarn classic
2. 进入本地仓库目录：

   cd ~/wherever/PX4-user_guide

3. 安装依赖项（包括 Vitepress）：

   yarn install

4. 预览并启动文档服务：

   yarn start

   • 开发/预览服务器构建文档后（首次构建不到一分钟），会显示您可以预览网站的 URL，例如：http://localhost:5173/px4_user_guide/。
   • 在终端提示符下按 CTRL + C 停止服务。
5. 您可以像部署时一样构建文档：

   # Ubuntu
   yarn docs:build
   
   # Windows
   yarn docs:buildwin

TIP

使用 yarn start 可以 实时预览 您所做的更改（文档更新和服务响应速度非常快）。在提交 PR 之前，您还应该使用 yarn docs:build 进行构建，因为这可以发现使用 yarn start 时看不到的问题。

源代码结构

本指南使用 Vitepress 工具链。

总体情况如下：

• 页面使用 Markdown 单独编写在不同的文件中。
  • 语法几乎与 GitHub 维基使用的语法相同。
  • Vitepress 还支持一些 Markdown 扩展。除了 提示、警告等 之外，我们尽量避免使用这些扩展。这一点可能会重新考虑，因为有些扩展选项很有趣！
• 这是一本 多语言 书籍：
  • 每种语言的页面都存储在以相应语言代码命名的文件夹中（例如，“en” 表示英语，“zh” 表示中文，“ko” 表示韩语）。
  • 仅编辑文件的英语（/en）版本。我们使用 Crowdin 来管理翻译。
• 所有页面必须位于 /en 下的适当命名的子文件夹中（例如，本页面位于 en/contribute/ 文件夹中）。
  • 这样做可以使链接更方便，因为其他页面和图像的相对层级始终保持一致。
• 书籍的 结构 在 SUMMARY.md 中定义。
  • 如果您向指南中添加了新页面，必须同时在该文件中添加一个条目！

  TIP

  这不是 “标准的 Vitepress” 定义侧边栏的方式（摘要文件由 .vitepress/get_sidebar.js 导入）。

• 图像必须存储在 /assets 的子文件夹中。该文件夹比内容文件夹低两层，因此如果您添加了一张图片，引用方式如下：

  ![图像描述](../../assets/path_to_file/filename.jpg)

• 名为 package.json 的文件定义了构建所需的任何依赖项。
• 当文件合并到该仓库的主分支时，会使用一个 Web 钩子来触发文档的重新构建。

文档规范指南

当您添加新页面时，必须同时将其添加到 en/SUMMARY.md 中！

内容布局规范

1. 文件和文件夹命名
   • 将新的 Markdown 文件放在 /en/ 下的适当子文件夹中，例如 /en/contribute/，不要进一步嵌套文件夹。
   • 将新的图像文件放在 /assets/ 下的适当嵌套子文件夹中，允许（建议）进行更深层次的嵌套。
   • 文件夹和文件使用描述性名称。特别是，图像文件名应描述其内容（不要命名为 “image1.png”）。
   • 使用小写文件名，并用下划线 (_) 分隔单词。
2. 图片
   • 新图片应放在 /assets/ 的子文件夹中（以便在不同翻译版本间共享）。
   • 图表优先使用 SVG 文件。截图优先使用 PNG 文件，而不是 JPG 文件。
3. 内容格式
   • 统一且谨慎地使用 “样式”（加粗、斜体 等），尽量少用。
     • 加粗 用于表示按钮按下和菜单定义。
     • 斜体 用于表示工具名称，如 QGroundControl 或 prettier。
     • 代码样式 用于表示文件路径、代码、未链接的参数名称以及在命令行中使用的工具，如 prettier。
   • 标题和页面标题应使用 “首字母大写”。
   • 页面标题应为一级标题 (#)，其他标题应为二级标题 (##) 或更低级别。
   • 不要为标题添加任何样式。
   • 不要翻译表示 info、tip 或 warning 声明的文本（例如 ::: tip），因为精确的文本是正确渲染侧边栏所必需的。
   • 优先在句子处换行，不要基于任意的行长度换行。
   • 使用 prettier 进行格式化（VSCode 有相关扩展可用于此操作）。
4. 视频
   • 可以使用 <lite - youtube videoid="<youtube - video - id>" title="your title"/> 格式添加 YouTube 视频（通过 [https://www.npmjs.com/package/lite - youtube - embed](https://www.npmjs.com/package/lite - youtube - embed) 自定义元素支持，该元素还有其他参数可供传递）。
     • 谨慎使用教学视频，因为它们容易过时且难以维护。
     • 欢迎提供飞行器飞行的精彩视频。

许可证

将新文件添加到涵盖类似主题的文件夹中，然后按照现有结构在侧边栏（/en/SUMMARY.md）中引用它们！

翻译

有关翻译的信息，请参阅：翻译。

许可协议

所有 PX4/Dronecode 文档均可根据宽松的 CC BY 4.0 许可证免费使用和修改。