嵌入式物联网机器人自动驾驶智能硬件【免费下载链接】PX4-AutopilotPX4 Autopilot Software项目地址https://gitcode.com/gh_mirrors/px/PX4-Autopilot点击查看免费下载PX4 用户指南PX4 User Guide的源码就存放在 PX4-Autopilot 仓库的docs/目录中与飞控固件源码同库管理。本文以 docs/en/contribute/docs.md 为骨架完整讲解从在 GitHub 网页上快速改错别字到用 Git 工作流新增整页文档、用 Vitepress 本地构建验证渲染效果的完整贡献链路并深入当前仓库的docs/目录结构、docs/package.json构建脚本与风格规范帮助你理解这套文档即代码的工作方式。读完本文你将掌握在线编辑入口的使用方法、标准 Fork 工作流中的每一步 Git 命令、本地预览与生产构建的完整命令序列以及新增页面时必须遵守的目录、命名与侧边栏注册规则。贡献方式总览先分清小改动与大改动PX4 官方欢迎任何形式的文档贡献从拼写、语法的小修小补到创建全新章节的大块内容。按照改动规模官方推荐两条不同路径改动类型推荐方式是否要求本地环境修改已有内容错别字、措辞、链接修正等GitHub 网页上的Edit on GitHub按钮直接编辑否只需 GitHub 账号新增页面、增删图片、大规模重构与改代码相同的 Git 工作流是需要 git、Node.js、Yarn无论走哪条路径都需要一个免费的GitHub。这一点也可以从仓库布局直接印证docs/下只有en/英文源文而zh/、ko/、uk/均为翻译语言目录由 docs/crowdin_docs.yml 配置驱动。快速修改GitHub 在线编辑对于已有页面的简单修改最快的路径是页面底部的Edit on GitHub链接。该链接会直接打开该页面在 GitHub 上的编辑界面操作步骤打开目标页面点击正文下方的Edit on GitHub链接在 GitHub 的在线编辑器中完成修改在编辑器下方按提示创建独立分支并提交pull requestPR。提交之后文档维护团队会进行评审要么直接合并要么与你沟通修改意见。在线编辑方式简单快捷但它只适合改已有内容不适合新增页面或更换图片——这类改动在网页编辑器里既不方便也不便于测试渲染效果官方建议改用下面的 Git 工作流。使用 Git 进行文档修改标准 Fork 工作流较大规模的改动新增页面、增删图片、结构调整遵循与改代码完全相同的流程Fork → Clone → 改文档 → 本地构建验证 → 分支提交 → 提 PR。文档源码就在 PX4-Autopilot 仓库的docs/子目录中英文源文位于docs/en/子目录可直接编辑。获取文档源码如果你还没有本地仓库副本先完成以下准备下载并安装 git从 git 官网获取对应系统版本注册 GitHub 账号如尚未注册在 GitHub 上 Fork 一份 PX4-Autopilot 仓库将 Fork 出来的仓库克隆到本地cd ~/wherever/ git clone https://github.com/your git name/PX4-Autopilot.git例如GitHub 账号为john_citizen的用户克隆自己的 Forkgit clone https://github.com/john_citizen/PX4-Autopilot.git进入本地仓库目录cd ~/wherever/PX4-Autopilot添加名为upstream的remote指向 PX4 官方版本git remote add upstream https://github.com/PX4/PX4-Autopilot关于 remote 的概念需要澄清一下remote是对某个远程仓库的句柄。克隆时默认会创建名为origin的 remote指向你自己的 Fork上面这条命令新增的upstream则指向 PX4 项目官方仓库。origin负责推送你的改动upstream负责拉取官方最新代码。如果你已经有 PX4-Autopilot 的克隆可以直接跳过本小节。制作并推送文档改动在本地仓库中按以下顺序操作将本地main分支同步到官方最新git checkout main git fetch upstream main git pull upstream main为你的改动创建新分支git checkout -b your_feature_branch_name该命令会在本地创建并切换到一个名为your_feature_branch_name的分支。分支命名建议使用能概括改动主题的名称例如docs_add_failsafe_guide。按需修改文档新增、修改、删除均可具体规范见后文风格指南将改动加入暂存区并提交git add file name git commit -m your commit message提交信息请遵循 Conventional Commits 规范详见 docs/en/contribute/code.md#commits-and-commit-messages——例如文档类改动通常写作docs(scope): 简述改动PX4 官方对所有 commit message 与 PR 标题均强制要求该格式将本地分支推送到你的 GitHub Fork 仓库git push origin your_feature_branch_name在浏览器中打开你的 Fork 仓库页面此时应能看到新分支已推送的提示横幅创建 Pull Request点击新分支提示横幅右侧的绿色Compare Create Pull Request按钮PR 模板会自动生成其中会列出你的 commit你需要填写一个有意义的标题单 commit 的 PR 通常直接用 commit message和正文说明为什么做了这些改动、改了什么给 PR 加上Documentation标签。至此提交完成。PX4 用户指南的维护者会评审你的贡献并决定是否合入。评审期间请定期查看是否有针对改动的提问。从仓库中的配套文档可以看到更多细节docs/en/contribute/git_examples.md完整演示了贡献代码/文档到 PX4的端到端流程含git remote -v校验、git rebase main保持线性历史、git push --force-with-lease处理评审后重推等进阶操作它与本文属于同一套贡献流程可互为补充。本地构建用 Vitepress 验证渲染效果在提交 PR 之前官方强烈建议先在本地构建文档确认改动渲染正确。这是文档即代码流程中最关键的验证环节。安装前置依赖安装 Vitepress 的前置条件Node.js 18Yarn classic经典版 Yarn当前仓库 docs/package.json 中声明了vitepress: ^1.6.3这一版本正是要求 Node.js 18 及以上与文档中的版本要求一致。进入本地仓库的docs子目录cd ~/wherever/PX4-Autopilot/docs安装依赖包括 Vitepress 本身yarn install4.可选如果你的改动涉及参数parameter或模块module文档先构建 PX4 元数据详见下文构建 PX4 文档元数据。启动开发预览服务器yarn start首次构建需要不到一分钟完成后终端会显示预览地址形如http://localhost:5173/px4_user_guide/按CTRLC即可停止服务。yarn start实际上是docs:devvitepress dev .的别名见 docs/package.json。它支持边改边看——保存文档后页面会快速热更新非常适合迭代式修改。在本地编辑器中打开当前页面启动预览前可以通过EDITOR环境变量指定本地文本编辑器这样每个页面底部的Open in your editor链接它会替代原来的Open in GitHub链接就能直接在当前编辑器中打开对应源文件Windowsset EDITORcodeLinuxexport EDITORcode然后照常执行yarn start。生产构建按部署方式完整构建文档# Ubuntu yarn docs:build # Windows yarn docs:buildwin从 docs/package.json 可以看到这两个脚本的真实定义docs:build等价于docs:build_ubuntu即NODE_OPTIONS--max-old-space-size8192 vitepress build .为 Node 分配 8 GB 内存上限避免大型文档站构建时 OOMdocs:buildwin则是set NODE_OPTIONS--max_old_space_size8192 set CItrue vitepress build .。如果改动中引用了新链接、新锚点等静态分析可见的内容docs:build能暴露出yarn start下不易察觉的问题因此提交 PR 前务必执行一次。构建 PX4 文档元数据PX4 元数据参数、模块、机架等由源码生成的内容不会在你修改源码后自动同步进本地文档树。如果新页面引用了新增的参数、模块、机架等生成内容本地测试时可能因此出现坏链。在Ubuntu上可用一条命令生成元数据并拷贝进文档树# Ubuntu yarn build_docs_metadata_ubuntu该脚本在 docs/package.json 中定义为(cd .. Tools/ci/metadata_sync.sh --generate Tools/ci/metadata_sync.sh --sync)即先在仓库根目录用 Tools/ci/metadata_sync.sh 生成、再同步回文档树。注意生成的元数据文档不应包含进 PR会干扰评审因为元数据会在 PR 合入 main 时自动重新生成即便误加了也没关系合入时会被覆盖。检查失效链接对整个文档库执行坏链检查# Ubuntu yarn linkchecklinkcheck在 docs/package.json 中的定义为markdown_link_checker_sc -r .. -d docs -e en -i assets -u docs.px4.io即用markdown_link_checker_sc工具扫描docs目录排除en之外的翻译目录、忽略assets资源目录来定位失效的内部与外部链接是 PR 提交前的重要质量闸门。文档源码结构一份仓库一套 Vitepress 站点PX4 用户指南使用Vitepress工具链构建其源码结构与当前仓库的docs/目录一一对应页面 独立的 Markdown 文件。语法与 GitHub Wiki 几乎相同Vitepress 还支持一些 markdown 扩展但官方尽量少用仅保留::: tip、::: warning这类提示框语法。多语言布局。每种语言的页面存放在以语言代码命名的文件夹中en英文、zh中文、ko韩文、uk乌克兰文均可在当前仓库docs/下直接看到。只编辑英文/en版本翻译由 Crowdin 管理。目录组织。所有页面必须放在/en下语义恰当的子文件夹中例如本页位于en/contribute/。这样做的原因是页面与图片始终处于相同的相对层级便于链接书写。站点结构由SUMMARY.md定义。新增页面后必须在 docs/en/SUMMARY.md 中登记条目否则页面不会出现在侧边栏。这份文件不是标准 Vitepress定义侧边栏的方式——它会被站点构建脚本文档中提到.vitepress/get_sidebar.js导入在当前仓库中侧边栏相关逻辑由 docs/scripts/gen_alt_sidebar.py 等脚本辅助生成。图片存放于/assets子目录。它位于内容目录往下两级因此引用图片时路径形如Image Description实际使用中需注意原文档中的此类相对路径是以该文档自身位置为基准的在仓库内查看时应换算为从仓库根目录出发的完整路径例如本页引用的按钮截图实际位于 docs/assets/vuepress/vuepress_edit_page_on_github_link.png。package.json声明构建依赖。当前仓库 docs/package.json 中列出了 Vitepress、lite-youtube-embed视频组件、markdown-it-mathjax3数学公式、markdown_link_checker_sc坏链检查等依赖并集中定义了本文提到的所有 yarn 脚本。Webhook 自动重建。仓库中文件合并进master/main分支时webhook 会触发站点自动重新构建发布。新增页面别忘了注册到 SUMMARY.md新增页面的流程与修改已有页面完全一样唯一的额外要求是新页面必须登记进en/SUMMARY.md否则页面内容虽存在于仓库中却不会出现在用户指南的侧边栏导航中等于不可达。新增页面的位置选择也有讲究把新文件放进主题相近的文件夹中并在侧边栏/en/SUMMARY.md中按照既有结构插入对应条目保持导航层级与内容分类的一致性。风格指南让文档可读、可维护、可翻译提交 PR 前请对照以下风格规范自查1. 文件与命名新 Markdown 文件放入/en/下合适的子文件夹如/en/contribute/不要继续嵌套多层文件夹新图片放入/assets/下合适的嵌套子文件夹嵌套层级可以更深文件夹与文件名要具有描述性尤其是图片文件名应描述其内容不要命名成image1.png文件名使用小写单词间用下划线_分隔。2. 图片在保证清晰可用的前提下使用最小尺寸、最低分辨率的图片降低低带宽用户的下载成本新图片创建在/assets/的子文件夹中便于翻译版本之间共享示意图优先使用SVG格式截图优先使用PNG优于 JPG。3. 内容拼写与语法遵循**英式英语UK**惯例行业标准软件术语除外如 dialog、program、disk排版样式加粗、斜体等使用要一致且克制加粗用于按钮和菜单名称斜体用于工具名称如QGroundControl、prettier代码用于文件路径、代码、未链接的参数名、命令行工具名。标题和页面标题使用首字母大写First Letter Capitalisation页面标题必须是一级标题#其余标题应为二级##或更低层级标题中不要附加任何样式不加粗、不斜体不要翻译info、tip、warning等提示块声明文字如::: tip因为这段精确文本是提示框正确渲染所必需的不要按任意行长换行而是在句子或段落边界处换行使用prettier进行格式化VSCode 有相应插件。4. 视频YouTube 视频可通过lite-youtube videoidyoutube-video-id titleyour title/格式嵌入由lite-youtube-embed自定义元素支持该元素还有更多可选参数且该依赖已声明在 docs/package.json 中教学类视频慎用——它们容易过时、维护成本高但飞行器酷炫的飞行视频永远欢迎。改动放哪里按主题归类 侧边栏登记新增文件应放在覆盖相似主题的文件夹中然后在侧边栏/en/SUMMARY.md中按既有结构登记。这套目录语义化 侧边栏集中注册的机制保证了大型文档站点在多人协作下仍能保持导航结构清晰、链接稳定。翻译与许可翻译工作通过Crowdin在线工具完成Crowdin 自动从 GitHub 导入英文源文译者完成翻译与审校后Crowdin 以 Pull Request 形式把翻译结果导出回 GitHub。具体参与方式加入 Crowdin、选择语言项目、申请加入翻译团队等详见 docs/en/contribute/translation.md。许可协议所有 PX4/Dronecode 文档均可在宽松的CC BY 4.0许可下自由使用与修改。这在仓库中也有直接依据docs/LICENSE 为许可证文本docs/package.json 中亦声明license: CC-BY-4.0。小结PX4 用户指南的贡献流程可以用一条主线概括英文源文在docs/en/小改动走 GitHub 在线编辑大改动走 Fork 分支 PR 的 Git 工作流合入前用 Vitepressyarn start预览、yarn docs:build生产构建、yarn linkcheck查坏链验证渲染质量新增页面务必登记进docs/en/SUMMARY.md翻译交给 Crowdin、许可遵循 CC BY 4.0。理解了这条链路你既能快速修正文档中的任何小问题也能以与提交代码相同的方式为这份用户指南贡献完整的新章节。赞分享嵌入式物联网机器人自动驾驶智能硬件【免费下载链接】PX4-AutopilotPX4 Autopilot Software项目地址https://gitcode.com/gh_mirrors/px/PX4-Autopilot点击查看免费下载相关推荐PX4/PX4-Autopilot 文档贡献指南从编辑到构建全流程PX4/PX4 Autopilot 文档贡献指南从编辑到构建全流程 前言 PX4/PX4 Autopilot 作为开源飞控系统其文档质量直接影响用户的使用体嵌入式物联网机器人自动驾驶智能硬件Apache Arrow 文档贡献实战指南定位源文件、在线编辑与本地构建Apache Arrow 文档贡献实战指南定位源文件、在线编辑与本地构建 本文面向希望参与 Apache Arrow 项目文档改进的开发者与使用者系统讲解从数据工程大数据序列化数据分析为 Argo Workflows 贡献文档写作规范、本地构建与 PR 全流程指南为 Argo Workflows 贡献文档写作规范、本地构建与 PR 全流程指南 本文是一份面向开发者的 Argo Workflows 文档贡献实操指南围绕云原生容器编排工作流自动化任务调度后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考