# 为文件做出贡献

欢迎为《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 (打开新窗口) 执照。