Build Instructions
本文档包含有关如何构建 frc-docs 网站的 HTML ，PDF 和 EPUB 版本的信息。 frc-docs 使用 Sphinx 作为文档生成器。本文档还假定您具有 Git 和控制台命令的基本知识。
Prerequisites
确保已安装 Git ，并使用 git clone https://github.com/wpilibsuite/frc-docs.git. 克隆了 frc-docs 存储库。
Text Editors / IDE
For development, we recommend that you use VS Code along with the reStructuredText extension. However, any text editor will work.
By default, the reStructuredText extension enables linting with all doc8 features enabled. As frc-docs does not follow the line length lint, add the following to your VS Code settings.json to disable line length linting.
"restructuredtext.linter.doc8.extraArgs": [
"--ignore D001"
]
Windows
备注
MikTeX and rsvg-convert are not required for building HTML, they are only required for Windows PDF builds.
MiKTeX (Only needed for PDF builds)
rsvg-convert (Only needed for PDF builds)
通过在安装 Python 时选择开关 Add Python to PATH 确保 Python 在您的路径中。
安装 Python 之后，打开 Powershell。然后导航到 frc-docs 目录。运行以指令： pip install -r source/requirements.txt
Install the missing MikTex packages by navigating to the frc-docs directory, then running the following command from Powershell: miktex --verbose packages require --package-id-file miktex-packages.txt
Linux（Ubuntu）
$ sudo apt update
$ sudo apt install python3 python3-pip
$ python3 -m pip install -U pip setuptools wheel
$ python3 -m pip install -r source/requirements.txt
$ sudo apt install -y texlive-latex-recommended texlive-fonts-recommended texlive-latex-extra latexmk texlive-lang-greek texlive-luatex texlive-xetex texlive-fonts-extra dvipng librsvg2-bin
Building
打开 Powershell Window 或终端，然后直接导航到克隆的 frc-docs 目录。
PS > cd "%USERPROFILE%\Documents"
PS C:\Users\Example\Documents> git clone https://github.com/wpilibsuite/frc-docs.git
Cloning into 'frc-docs'...
remote: Enumerating objects: 217, done.
remote: Counting objects: 100% (217/217), done.
remote: Compressing objects: 100% (196/196), done.
remote: Total 2587 (delta 50), reused 68 (delta 21), pack-reused 2370
Receiving objects: 100% (2587/2587), 42.68MiB | 20.32 MiB/s, done.
Receiving deltas: 100% (1138/1138), done/
PS C:\Users\Example\Documents> cd frc-docs
PS C:\Users\Example\Documents\frc-docs>
Lint Check
备注
Lint Check 将不会检查 Windows上的行尾，因为存在行尾错误。有关更多信息，请参见 this issue for more information.
鼓励您检查对 linter 所做的任何更改。如果编译器没有通过，这 will 使编译器失败。要检查，请运行 .\make lint
Link Check
链接检查器确保文档中的所有链接都能解析。如果编译器没有通过，这**will** 使编译器失败。要检查，请运行``。make linkcheck``
Image Size Check
Please run .\make sizecheck to verify that all images are below 500KB. This check will fail CI if it fails. Exclusions are allowed on a case by case basis and are added to the IMAGE_SIZE_EXCLUSIONS list in the configuration file.
Redirect Check
已移动或重命名的文件必须在 source 中的 redirects.txt 文件中有新位置（或用 404 替换）。
重定向编写器会自动将重命名/移动的文件添加到重定向文件中。运行 .\make rediraffewritediff
备注
如果移动了文件的同时并对其进行了实质性更改，则重定向编写器不会将其添加到 redirects.txt 文件中，并且需要手动更新 redirects.txt 文件。
重定向检查器确保所有文件都有有效的重定向。如果编译器没有通过，这 will 使编译器失败。要进行检查，请运行 .\make rediraffecheckdiff，以验证所有文件都已重定向。此外，可能需要运行一个 HTML 以确保所有文件正确重定向。
构建 HTML
输入指令 .\make html 以生成 HTML 内容。该内容位于存储库根目录的 build/html 目录中。
Building PDF
警告
请注意，Windows 上的 PDF 程序可能会导致 SVG 内容的图像失真。这是因为 Windows 上缺少 librsvg2-bin 支持。
输入指令 .\make latexpdf 以生成 PDF 内容。 PDF 位于存储库根目录的 build/latex 目录中。
Building EPUB
输入指令 .\make epub 以生成 EPUB 内容。 EPUB 位于存储库根目录的 build/epub 目录中。
添加Python第三方库
重要
在以任何方式修改frc-docs依赖关系之后，必须通过从目录的根目录运行“ poetry export -f requirements.txt –output source / requirements.txt –with-hashhes”来重新生成“ requirements.txt”。回购。
frc-docs使用Poetry <https://python-poetry.org/>`__来管理其依赖项，以确保构建可复制。
备注
诗不是构建和贡献于frc-docs内容所必需的。 *仅*用于依赖项管理。
安装诗歌
Ensure that Poetry is installed. Run the following command: pip install poetry.
添加依赖
Add the dependency to the [tool.poetry.dependencies] section of pyproject.toml. Make sure to specify an exact version. Then, run the following command: poetry lock --no-update.
更新顶级依赖关系
Update the dependency’s version in the [tool.poetry.dependencies] section of pyproject.toml. Then, run the following command: poetry lock --no-update.