PX4/PX4-Autopilot 文档贡献指南：从编辑到构建全流程

PX4/PX4-Autopilot 文档贡献指南：从编辑到构建全流程

PX4-Autopilot PX4 Autopilot Software 项目地址: https://gitcode.com/gh_mirrors/px/PX4-Autopilot

前言

PX4/PX4-Autopilot 作为开源飞控系统，其文档质量直接影响用户的使用体验。本文将详细介绍如何为PX4项目贡献文档，包括快速修改、本地构建测试以及文档风格规范等核心内容。

文档修改方式

快速修改方式

对于已有文档的简单修改（如错别字、语法修正等），可以直接通过在线编辑器完成：

1. 打开需要修改的文档页面
2. 点击页面底部的编辑按钮
3. 在打开的编辑界面中进行修改
4. 提交修改请求

这种方式适合对现有内容进行微小调整，系统会自动创建分支并引导你提交修改请求。

使用Git进行复杂修改

对于需要添加新页面、修改图片等更复杂的修改，建议使用完整的Git工作流程：

1. 获取PX4源代码到本地
2. 创建新的开发分支
3. 进行文档修改
4. 本地构建测试
5. 提交修改请求

本地开发环境搭建

获取文档源代码

PX4文档源代码位于项目仓库的/docs目录下，其中英文文档位于/docs/en子目录。获取源代码的步骤如下：

1. 安装Git工具
2. 克隆你的项目副本到本地：

   git clone https://github.com/<your_username>/PX4-Autopilot.git
   

3. 添加上游仓库引用：

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

本地构建文档

PX4文档使用Vitepress构建，本地构建步骤如下：

1. 安装Node.js 18+和Yarn classic
2. 进入文档目录：

   cd PX4-Autopilot/docs
   

3. 安装依赖：

   yarn install
   

4. 启动本地预览服务：

   yarn docs:dev
   

5. 构建完整文档：

   yarn docs:build
   

本地预览服务启动后，可以通过浏览器访问http://localhost:5173/px4_user_guide/查看效果。

文档结构规范

文件组织

• 所有文档文件必须放在/en下的适当子目录中
• 图片等资源文件放在/assets子目录中
• 使用描述性的文件名，单词间用下划线连接

内容格式

1. 标题：

   • 页面标题使用一级标题(#)
   • 其他标题从二级标题(##)开始
   • 使用首字母大写

2. 样式使用：

   • 加粗用于按钮操作和菜单定义
   • _斜体_用于工具名称
   • 代码样式用于文件路径、参数名等

3. 其他规范：

   • 尽量保持简洁的风格
   • 按句子换行，不要随意断行
   • 使用prettier工具格式化文档

添加新内容

添加新文档时需要：

1. 将新文件放在适当的/en子目录下
2. 在/en/SUMMARY.md中添加对应条目
3. 确保内容符合上述格式规范

视频内容

可以通过特定格式添加YouTube视频：

<lite-youtube videoid="<youtube-video-id>" title="your title"/>

但建议谨慎使用视频内容，因为视频容易过时且难以维护。

许可证说明

PX4文档采用CC BY 4.0许可协议，允许自由使用和修改。

通过遵循这些指南，你可以有效地为PX4项目贡献高质量的文档内容，帮助全球开发者更好地使用这一开源飞控系统。

PX4-Autopilot PX4 Autopilot Software 项目地址: https://gitcode.com/gh_mirrors/px/PX4-Autopilot