维基编辑 - 设置环境

在向维基提交大的改动之前，最好先检查页面是否正确显示，包括检查所有图片和链接是否正确显示。本页介绍了如何在本地计算机上 "构建 "维基（即把原始文件和图片文件转换成一组 html 页面），以便进行这些检查。

有几种方法可以设置本地构建环境：

1. 使用 Vagrant 文件 的根目录下，创建一个安装了所有必要软件包的 Linux 虚拟机。这是首选且受支持的方法。

2. 使用 Dockerfile 的根目录下，创建一个安装了所有必要软件包的 Linux 容器。

3. 或者只需在本地 Linux 或 Windows 机器上安装所需的库，具体操作说明如下。

分叉、克隆和更新你的维基副本

首先，维基应被分叉和克隆，就像 开发人员为飞行代码所做的工作.

1. 创建一个 Github 账户 如果您还没有

2. 安装 Git 客户端

3. 叉子 的 ardupilot_wiki 在 GitHub 上创建您自己的副本（注意，链接说明针对的是 ardupilot 飞行代码，因此应将 "ardupilot "替换为 "ardupilot_wiki"）。

   

4. 克隆 将 GitHub 上的 ardupilot_wiki 复制到本地计算机（注意，链接说明针对的是 ardupilot 飞行代码，因此应将 "ardupilot "替换为 "ardupilot_wiki"）。

   git 复制 https://github.com/YOURID/ardupilot_wiki.git
   

在安装和开发新贡献时，请务必保持你的分叉仓库在本地和 GitHub 上的更新。开始修改时，请务必在本地创建一个工作分支，将该分支推送到 GitHub 仓库，然后创建 PR（从 GitHub 仓库向 Wiki 仓库提交拉取请求），其方式类似于创建 PR 代码.

git 远程 增加 上游部门 https://github.com/ArduPilot/ardupilot_wiki.git git 销售点 git master 取得 上游 git 躏 upstream/master git 推动 -f 产地 师

设置环境

在 Linux（或 WSL）中设置

在克隆的 ardupilot_wiki 目录中运行以下命令：

./Sphinxsetup.sh

然后跳转到 "构建维基"。

在 Windows 中设置

无需在 WSL 或 Cygwin 中运行。ArduPilot wiki 可直接在 Windows 上构建。

确保最新版本的 Python 并在安装时选择了 "Add Python 3.x to PATH"（将 Python 3.x 添加到 PATH）选项。

从克隆的 ardupilot_wiki 目录中运行以下命令，确保以管理员身份运行（右键单击 -> 以管理员身份运行）：

./Sphinxsetup.bat

然后跳转到 "构建维基"。

使用 Vagrant 进行设置

1. 下载并安装 无人车UGV

2. 下载并安装 Oracle VirtualBox.

3. Windows 用户应在启动 vagrant 前在电脑上安装 SSH 客户端。Vagrant 需要 SSH 客户端程序来访问开发容器。我们使用 MLS-Software 的 OpenSSH 打包程序取得了巨大成功。 这里

建立文档的主要步骤是

1. 在 ardupilot_wiki repo 的根目录下打开命令提示符，启动 Vagrant。首次运行可能需要 30 分钟以上才能完成。

   CD ardupilot_wiki 无人车UGV 向上
   

2. 通过 SSH 登录 Vagrant（Windows 用户可能需要在 PATH 中添加 SSH）

   流浪汉 ssh
   

3. 在 SSH shell 中导航到 /vagrant 目录，然后开始构建。

   CD /vagrant python3 update.py
   

使用 Docker 进行设置

1. 下载并安装 Docker 官方文件.

2. 在 ardupilot_wiki 软件源的根目录下打开命令提示符，为维基构建 docker 容器：

   CD ardupilot_wiki docker 构建 . -t ardupilot_wiki
   

这将构建一个包含所有软件包设置的 docker 镜像，用于构建维基，并将其命名为 ardupilot_wiki.

1. 使用容器通过共享卷构建 wiki，在电脑上获取构建结果：

   装卸工 运行 --rm -它 -v "；${工务司}:/ardupilot_wiki"； -u "；$(本我 -u):$(本我 -g)"； ardupilot_wiki python3 update.py
   

这将用 update.py 如 建立维基.......。 -v 用于将包含所有文档的当前目录的内容共享给容器。当前目录 -u 用来让 docker 使用与当前用户相同的权限。有了这两条命令，生成的构建文件就可以像下面这样访问了 检查结果

建立维基

如上文 vagrant 说明的最后一步所示，使用 update.py 来构建部分或全部维基。

python3 update.py (至 构建 一应俱全 维基)
python3 update.py --网站 旋翼飞行器  (至 构建 只是 的 旋翼飞行器 维基)
python3 update.py --网站 飞机   (至 构建 只是 的 飞机 维基)
python3 update.py --网站 无人车UGV   (至 构建 只是 的 无人车UGV 维基)
python3 update.py --网站 设计     (至 构建 只是 此 开发人员 维基)

update.py 脚本会将公共文件复制到每个维基子目录，然后构建每个维基。

构建完成后，维基文件将被复制到 --destdir.默认情况下，在 Linux 中，这是 /var/sites/wiki/web 而在 Windows 中则是 ...\wiki.

备注

脚本将显示每个维基的构建输出。应检查其中是否有警告和错误。

有关维基站点建设和基础设施的详细信息，请参见 这里.

检查结果

使用您最喜欢的网络浏览器，打开本地构建的维基站点，该站点应靠近 ardupilot_wiki 复制到的位置

• Copter 查找 ardupilot_wiki/copter/build/html/index.html

• 飞机可查找 ardupilot_wiki/plane/build/html/index.html

• 对于罗孚，请查找 ardupilot_wiki/rover/build/html/index.html

• 开发人员查找 ardupilot_wiki/dev/build/html/index.html

构建选项

用法： update.py [-h] [--site SITE] [--clean] [--cached-parameter-files] [--parallel PARALLEL] [--destdir DESTDIR] [--enablebackups] [---backupdestdir BACKUPDESTDIR] [--paramversioning] [--verbose] [--fast] 根据需要复制常用文件，删除不相关的维基内容 可选参数：-h，--help 显示此帮助信息并退出 --site SITE 如果只想复制到一个站点，可以这样做。否则将被复制。--clean进行非常干净的编译--重置 git 为 master head（并清理输出中的重复内容）。--cached-parameter-files（缓存参数文件） 不重新下载参数文件 --parallel PARALLEL（并行 PARALLEL） 限制并行编译，-1 表示无限制 --destdir DESTDIR Destination directory for compiled docs --enablebackups（启用备份） 在--backupdestdir 文件夹中启用多个备份，最多可达常数 N_BACKUPS_RETAIN ---backupdestdir BACKUPDESTDIR Destination directory for compiled docs --paramversioning 根据固件 repo 为每辆车构建多个参数页面。--verbose 显示调试输出 --fast 使用已下载的参数、日志信息和视频缩略图进行增量编译，而不是在编译前进行清理。

大多数构建选项只能在构建维基的服务器上使用。编辑人员最有可能发现有用的选项是 -网站 SITE 和 -快. -网站 SITE 允许构建单个维基，而不是构建所有维基。这已经大大提高了速度，但有时需要检查多个维基中的更改。维基 -快 选项可跳过下载载具参数、日志信息和视频缩略图所需的数据。在进行小的格式更改或不需要新参数/日志信息时，该选项会很有帮助。新添加的视频缩略图将被下载并缓存，以便下一次创建时使用 -快 启用。

RST 编辑/预览

本节中介绍的工具可以使 RST 文件的编辑变得更容易，并减少预览更改所需的时间。

备注

RST 渲染工具可用于快速预览文档中的微小改动。由于这些工具是为通用的 reStructuredText 而设计的（它们并不 "支持 Sphinx"），因此渲染效果并不完美。因此，我们建议您使用 Sphinx 构建文档，以便在提出文档拉取请求前进行最终审核。

Windows操作系统上的 RST 渲染

结合使用两个 Windows 工具可以帮助您预览修改：

• 用于 RST 文件的 Notepad++ 插件

• restview（RST 文件的即时渲染器）

• PyCharm

在修改过程中，记事本++ 插件可帮助你完成代码和语法高亮显示。Restview 可即时渲染 RST 文件，也就是说，对 RST 文件的每次修改都能在网络浏览器中立即显示出来。

Notepad++ 插件的安装方法在插件网站上有明确说明（见上文）。

Restview 可与以下设备一起安装

python3 -m pip install restview

restview 可执行文件将安装在 脚本 文件夹。Restview 将启动即时 HTML 渲染，并在您喜欢的网络浏览器中打开一个标签页。

例如

如果您在本地维基资源库的根文件夹中：

启动 \commonsource\docs\common-wiki_editing_guide.rst

Linux 上的 RST 渲染

• 再文本 是一款 Linux 工具，可在单个应用程序中提供语法高亮和基本的即时渲染功能。

备注

虽然该工具基于 Python，但不要在 Windows 系统上试用，因为它很容易崩溃（网站上也有说明）。

• PyCharm