为文件做出贡献

欢迎为《PX4 用户指南》投稿；从简单的拼写和语法修正，到创建全新的章节。

本专题介绍了如何进行更改和测试。最后还有一个基本的风格指南。

备注

您需要一个（免费） Github 账户，为指南做出贡献。

Github 中的快速更改

对 现有内容 可通过点击 在 GitHub 上编辑 链接（可打开 Github 上的页面进行编辑）。

编辑现有页面

1. 打开页面。
2. 点击 在 GitHub 上编辑 页面内容下方的链接。
3. 进行所需的更改。
4. 在 Github 页面编辑器下方，会提示您创建一个单独的分支，然后引导您提交一个 拉取请求.

文档团队将审查该请求，然后将其合并或与您合作更新。

使用 Git 进行更改（新增页面和图像）

更实质性的更改，包括添加新页面或添加/修改图片，并不容易在 Github 上进行（或正确测试）。对于这类更改，我们建议使用与 代码:

1. 使用 Git 工具链，将文档源代码导入本地计算机。
2. 根据需要修改文件（添加、更改、删除）。
3. 测试 使用 Vitepress 可以正确地构建。
4. 为你的修改创建一个分支，并创建一个拉取请求（PR），将其拉回文档中。

下面将介绍如何获取源代码、本地构建（用于测试）和修改代码。

获取/推送文档源代码

要在本地计算机上获取库源代码，您需要使用 git 工具链。下面的说明介绍了如何在本地电脑上获取并使用 git。

1. 下载 git https://git-scm.com/downloads

2. 注册 如果您还没有，请使用 Github

3. 创建一个 PX4 用户指南资源库 在 Github (此处的说明).

4. 克隆（复制）你的分叉版本库到本地电脑：

   CD ~/wherever/
   Git 复制 https://github.com/<；您的 Git 命名e>；/PX4-user_guide.git

   例如，为 Github 账户为"john_citizen"的用户克隆 PX4 用户指南分叉：

   Git 复制 https://github.com/john_citizen/PX4-user_guide.git

5. 导航至本地存储库：

   CD ~/wherever/PX4-user_guide

6. 添加一个 远程 称为 "上游"，指向 PX4 版本的库：

   Git 远程 增加 上游部门 https://github.com/PX4/PX4-user_guide.git

   TIP

   远程 "是指向特定存储库的句柄。远程名为 产地 会在克隆版本库时默认创建，并指向 你的叉子 的指南。以上是创建一个新的远程 上游部门 指向文件的 PX4 项目版本。

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

   Git 销售点 -b <；您的特色分支名称e>；

   这会在你的计算机上创建一个本地分支，名为 您的特色分支名称.

8. 根据需要对文件进行修改（下文将对此提供一般性指导）

9. 一旦你对自己的改动感到满意，就可以使用 "commit" 将它们添加到本地分支中：

   Git 增加 <；文件 命名e>；
   Git 承诺 -m "<您的提交信息>"；

   有关良好的提交信息，请参考 源代码管理 节。

10. 将本地分支（包括添加到该分支的提交）推送到 Github 上的分叉仓库。

    Git 推动 产地 您的特色分支名称

11. 使用网络浏览器访问 Github 上的分叉仓库，例如 https://github.com/<您的 git 名称>/PX4-user_guide.git.在那里，你会看到一条信息：一个新的分支已被推送到你的分叉仓库。

12. 创建拉取请求 (PR)：

    • 在"新分支消息"（见前一步）的右侧，你应该能看到一个绿色按钮，上面写着"比较&创建拉取请求"。按下它。
    • 将创建一个拉取请求模板。它将列出您的提交，您可以（必须）添加一个有意义的标题（如果是单次提交的 PR，通常是提交信息）和信息（例如："您的提交"、"您的提交"、"您的提交"、"您的提交"）。说明原因.检查 其他请求 以作比较）

13. 您的工作完成了！现在，PX4 用户指南的维护者将查看您的贡献，并决定是否将其整合。请定期查看他们是否对您的修改有疑问。

在当地建设图书馆

在本地构建该库，以测试您所做的任何更改是否已正确呈现：

1. 安装 Vitepress 前提条件:

   • Nodejs 18+
   • 纱线经典

2. 导航至本地存储库：

   CD ~/wherever/PX4-user_guide

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

   纱 安装

4. 预览和服务图书馆：

   纱 启动

   • 一旦开发/预览服务器建立了库（第一次不到一分钟），它就会向你显示可以预览网站的 URL。网址如下 http://localhost:5173/px4_user_guide/.
   • 停止使用 CTRL+C 在终端提示符中输入

5. 您可以按照部署时的方法来构建库：

   # Ubuntu
   纱 文档：构建
   
   # 窗口
   纱 docs:buildwin

TIP

使用 起纱 预览更改 随心所欲 (文件更新和送达速度非常快）。在提交 PR 之前，您还应使用 yarn docs:build因为这样可以突出显示使用 起纱.

源代码结构

指南使用 Vitepress 工具链。

综上所述：

• 页面使用标记符（markdown）写入独立文件。

  • 语法与 Github 维基使用的语法几乎相同。
  • 维特普雷斯还支持一些 markdown扩展.我们尽量避免使用它们，除非 提示、警告等。.也许可以重新考虑这个问题--这里提供了一些有趣的选择！

• 这是一个 多语种 书：

  • 每种语言的页面都存储在以相关语言代码命名的文件夹中（例如，"en" 表示英语，"zh" 表示中文，"ko" 表示韩语）。
  • 只编辑英文 (/en)版本的文件。我们使用 Crowdin 来管理翻译。

• 所有页面都必须放在以下文件夹中的一个适当命名的子文件夹中 /en (例如，本页面位于文件夹 en/contribute/).

  • 这使得链接更容易，因为其他页面和图像总是处于相同的相对级别

• 结构 中定义的。 摘要.md

  • 如果您在指南中添加新页面，也必须在此文件中添加一个条目！

    TIP

    这不是标准的 vitepress 侧边栏定义方法（摘要文件通过以下方式导入 .vitepress/get_sidebar.js).

• 图像必须存储在 /资产.这是从内容文件夹向下的两个文件夹，因此，如果您添加了图片，就会像这样引用它：

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

• 一个名为 package.json 定义构建的任何依赖项。

• 网络钩子用于跟踪文件何时合并到该版本库的主分支，从而导致图书重建。

添加新页面

添加新页面时，还必须将其添加到 en/SUMMARY.md!

风格指南

1. 文件/文件名

   • 将新文件放入 /en/.不要再嵌套文件夹。
   • 使用描述性名称。特别是，图像文件名应描述其包含的内容。
   • 使用小写文件名，并用下划线 "_" 分隔单词；

2. 图片

   • 使用最小尺寸和最低分辨率，使图像仍然有用（这可降低带宽不足用户的下载成本）。
   • 新图像应在以下子文件夹中创建 /assets/ 默认情况下，它们可以在不同翻译之间共享）。

3. 内容

   • 统一使用"风格"（粗体、强调等）。
     • 粗体 按钮和菜单定义。
     • 强调 用于工具名称。- 否则尽量少用。
   • 标题和页面标题应使用"首字母大写"；
   • 页面标题应为一级标题（#）。所有其他标题应为 h2（##）或更低一级。
   • 不要为标题添加任何样式。
   • 不要翻译 前段 注意、提示或警告声明（例如 提示)，因为要正确显示注释，就必须有这一准确的文本。

在哪里添加更改？

根据现有结构添加新文件！

其中一些主要类别包括

• 发展：相关内容：
  • 发展平台（新模式、模块、飞行模式、硬件、软硬件结构和移植）。
  • 需要开发人员的专业知识才能复制的 "实验性"工作。
• 飞行：与驾驶标准飞行器有关的内容（飞行模式、启动、起飞、着陆）
• 基本配置：每辆车都需要进行的配置
• 高级配置：针对载具类型或部分用户的特定配置。
• 外围设备：有关可使用的不同硬件的文档。
  • 这还包括基本配置中未涵盖的硬件的设置和配置信息。
• 基本装配：自动驾驶仪及其主要外围设备的组装
• 机身建造：如何构建整个系统的示例。

翻译

有关翻译的信息，请参见 翻译.

许可证

根据许可条款，所有 PX4/Dronecode 文档均可自由使用和修改。 CC BY 4.0 许可证。