Build Instructions
This document contains information on how to build the HTML, PDF, and EPUB versions of the frc-docs site. frc-docs uses Sphinx as the documentation generator. This document also assumes you have basic knowledge of Git and console commands.
Prerequisites
Ensure that Git is installed and that the frc-docs repository is cloned by using git clone https://github.com/wpilibsuite/frc-docs.git.
You will need to install uv, a Python package and project manager. Follow the installation instructions for your operating system.
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 在您的路径中。
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
$ 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 will not check line endings on Windows due to a bug with line endings. See this issue for more information.
It’s encouraged to check any changes you make with the linter. This will fail CI if it does not pass. To check, run uv run .\make.bat lint
Link Check
The link checker makes sure that all links in the documentation resolve. This will fail CI if it does not pass. To check, run uv run .\make.bat linkcheck
Image Size Check
Please run uv run .\make.bat 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 替换）。
The redirect writer will automatically add renamed/moved files to the redirects file. Run uv run .\make.bat rediraffewritediff.
备注
如果移动了文件的同时并对其进行了实质性更改，则重定向编写器不会将其添加到 redirects.txt 文件中，并且需要手动更新 redirects.txt 文件。
The redirect checker makes sure that there are valid redirects for all files. This will fail CI if it does not pass. To check, run uv run .\make.bat rediraffecheckdiff to verify all files are redirected. Additionally, an HTML build may need to be ran to ensure that all files redirect properly.
构建 HTML
Type the command uv run .\make.bat html to generate HTML content. The content is located in the build/html directory at the root of the repository.
Building PDF
警告
请注意，Windows 上的 PDF 程序可能会导致 SVG 内容的图像失真。这是因为 Windows 上缺少 librsvg2-bin 支持。
Type the command uv run .\make.bat latexpdf to generate PDF content. The PDF is located in the build/latex directory at the root of the repository.
Building EPUB
Type the command uv run .\make.bat epub to generate EPUB content. The EPUB is located in the build/epub directory at the root of the repository.
添加Python第三方库
重要
After modifying frc-docs dependencies in any way, requirements.txt must be regenerated by running uv export --frozen --no-dev --no-editable -o source/requirements.txt from the root of the repo.
添加依赖
Add the dependency to the dependencies array in pyproject.toml. Make sure to specify an exact version. Then, run the following command: uv lock.
更新顶级依赖关系
Update the dependency’s version in the dependencies array in pyproject.toml. Then, run the following command: uv lock.