构建说明#
本文档包含关于如何构建HTML、PDF和EPUB版本的6940swerve-docs网站的信息。6940swerve-docs使用Sphinx作为文档生成器。本文档还假设你有 Git 和控制台命令的基本知识。
先决条件#
确保 Git 已经安装，并且通过使用 git clone https://github.com/wpilibsuite/frc-docs.git 克隆了6940swerve-docs仓库。
Windows#
备注
MikTeX和 rsvg-convert 在构建HTML时不需要，它们只在Windows PDF构建时需要。
Python 3.9 (Python >= 3.10是不兼容的。）
MiKTeX (只需要用于PDF构建)
通过在安装 Python 时选择 Add Python to PATH ，确保 Python 在你的路径中。
一旦Python安装完毕，打开Powershell。然后导航到6940swerve-docs目录。运行以下命令。pip install -r source/requirements.txt 。
通过导航到6940swerve-docs目录来安装缺少的MikTex软件包，然后从Powershell运行以下命令：mpm --verbose --require=@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
构建#
打开Powershell窗口或终端，导航到被克隆的6940swerve-docs目录。
PS > cd "%USERPROFILE%\Documents"
PS C:\Users\Example\Documents> git clone https://github.com/wpilibsuite/6940swerve-docs.git
Cloning into '6940swerve-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 6940swerve-docs
PS C:\Users\Example\Documents\6940swerve-docs>
Lint检查#
备注
由于行尾的错误，Lint Check不会在Windows上检查行尾。更多信息请参见 这个问题 。
我们鼓励你用 linter 检查你所做的任何改动。如果没有通过的话，这 会 让 buildbot 失败。要检查，请运行 .make lint 。
链接检查#
链接检查器会确保文档中的所有链接都能解决。如果没有通过，则 会 使构建机器人失败。要检查，请运行 .make linkcheck 。
图像大小检查#
请运行 .make sizecheck 来验证所有图片是否低于500KB。这个检查如果失败，CI就会失败。允许根据具体情况排除，并在配置文件中加入``IMAGE_SIZE_EXCLUSIONS`` 列表。
重定向检查#
被移动或重命名的文件必须在 source 中的 redirects.txt 文件中标明其新的位置（或用404替换）。
重定向编写器会自动将重命名/移动的文件添加到重定向文件中。运行 .\make rediraffewritediff 。
备注
如果一个文件既被移动又有实质性的改变，重定向编写者将不会把它添加到 redirects.txt 文件中，redirects.txt 文件将需要手动更新。
重定向检查器会确保所有文件都有有效的重定向。如果没有通过，则 会 使构建机器人失败。要检查的话，请运行 .make rediraffecheckdiff 来确认所有文件都被重定向了。此外，可能需要运行一个HTML构建，以确保所有文件都能正确重定向。
构建HTML#
Type the command .\make html to generate HTML content. The content is located in the build/html directory at the root of the repository.
构建PDF#
警告
请注意，在Windows上构建PDF可能会导致SVG内容的图像失真。这是由于Windows上缺乏librsvg2-bin的支持。
输入命令 .make latexpdf 来生成PDF内容。该PDF位于版本库根部的 build/latex 目录下。
构建EPUB#
输入命令 .make epub 来生成EPUB内容。EPUB位于版本库根部的 build/epub 目录下。
添加Python第三方库#
重要
在以任何方式修改了6940swerve-docs的依赖关系后，requirements.txt 必须通过运行 poetry export -f requirements.txt --output source/requirements.txt --without-hashes 从 repo的根目录中重新生成。
6940swerve-docs使用 Poetry 来管理其依赖关系，以确保构建是可重复的。
备注
Poetry是 不 需要建立和用于贡献6940swerve-docs内容的。它 只 用于依赖性管理。
安装Poetry#
确保Poetry已经安装。运行以下命令：pip install poetry 。
添加一个依赖关系#
在 pyproject.toml 的 [tool.poetry.dependencies] 部分添加该依赖关系。确保指定一个准确的版本。然后，运行以下命令。poetry lock --no-update 。
更新顶层依赖关系#
在 pyproject.toml 的 [tool.poetry.dependencies] 部分更新该依赖的版本。然后，运行以下命令。poetry lock --no-update 。