Instruções de Construção
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.
Pré-requisitos
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
Nota
MikTeX e rsvg-convert não são necessários para compilar HTML, eles são necessários apenas para compilações de PDF do Windows..
MiKTeX (Only needed for PDF builds)
rsvg-convert (Only needed for PDF builds)
Certifique-se de que o Python está em seu Path, selecionando a opção Add Python to PATH (Adicionar Python ao PATH) ao instalar o 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
Compilando
Abra uma janela Powershell ou terminal e navegue até o diretório frc-docs que foi clonado.
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>
Verificação por Linter
Nota
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
Verificação de Link
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
Verificação do Tamanho da Imagem
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.
Verificação de Redirecionamento
Os arquivos que foram movidos ou renomeados devem ter seu novo local (ou substituídos por 404) no arquivo redirects.txt em fonte.
The redirect writer will automatically add renamed/moved files to the redirects file. Run uv run .\make.bat rediraffewritediff.
Nota
Se um arquivo for movido e substancialmente alterado, o Redirect Writer não irá adicioná-lo ao arquivo redirects.txt, e o arquivo redirects.txt precisará ser atualizado manualmente.
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.
Compilando em 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.
Compilando em PDF
Aviso
Observe que a compilação em PDF no Windows pode resultar em imagens distorcidas para conteúdo SVG. Isso ocorre devido à falta de suporte a librsvg2-bin no Windows.
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.
Compilando em 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.
Adicionando Bibliotecas de Terceiros em Python
Importante
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.
Adicionando uma Dependência
Add the dependency to the dependencies array in pyproject.toml. Make sure to specify an exact version. Then, run the following command: uv lock.
Atualizando uma Dependência de Alto Nível
Update the dependency’s version in the dependencies array in pyproject.toml. Then, run the following command: uv lock.