PX4 用户指南（V1.12）

# 为文件做出贡献

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

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

备注

您需要一个（免费） Github (打开新窗口） 账户，为指南做出贡献。

# Github 中的快速更改

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

Vuepress：编辑页面按钮

编辑现有页面

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

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

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

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

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

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

# 获取/推送文档源代码

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

  1. 下载 git https://git-scm.com/downloads (打开新窗口）

  2. 注册 (打开新窗口） 如果您还没有使用 Github

  3. 创建一个 PX4 用户指南资源库 (打开新窗口） 在 Github (此处的说明 (打开新窗口）).

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

    CD ~/wherever/
Git 克隆 https://github.com/<；您的 Git 名字>；/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 checkout -b <；您的特色分支名称>；

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

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

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

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

    有关良好的提交信息，请参阅 捐款 节。

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

    Git push origin your_feature_branch_name

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

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

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

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

# 在当地建设图书馆

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

  1. 安装 Vuepress prerequiresites (打开新窗口）:
  2. 导航至本地存储库：
    CD ~/wherever/px4_user_guide
  3. 安装依赖项（包括 Vuepress）：
    纱 安装
  4. 预览和服务图书馆：
    纱 文档：开发
    • 现在，您可以在 http://localhost:8080/px4_user_guide/ 上浏览指南。
    • 停止使用 CTRL+C 在终端提示符中输入
  5. 使用
    # Ubuntu
纱 文档：构建
# 窗口
纱 docs:buildwin

TIP

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

# 源代码结构

指南使用 威压 (打开新窗口） 工具链。PX4 用户指南》有一些细微差别，主要与配置和设置有关。

综上所述：

  • 页面使用标记符（markdown）写入独立文件。
  • 这是一个 多语种 (打开新窗口） 书：
    • 每种语言的页面都存储在以相关语言代码命名的文件夹中（例如，"zh"表示中文，"ko"表示韩文）。
    • 只编辑英文 (/en)版本的文件。我们使用 Crowdin 来管理翻译。
  • 所有页面都必须放在以下文件夹中的一个适当命名的子文件夹中 /en (例如，本页面位于文件夹 en/contribute/).
    • 这使得链接更容易，因为其他页面和图像总是处于相同的相对级别
  • 结构 中定义的。 摘要.md
    • 如果您在指南中添加新页面，也必须在此文件中添加一个条目！

      TIP

      这不是定义侧边栏的标准 vuepress" 方法（摘要文件通过以下方式导入 .vuepress/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 (打开新窗口） 执照。

← 翻译 →