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.
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.
Assim que o Python estiver instalado, abra o Powershell. Em seguida, navegue até o diretório frc-docs. Execute o seguinte comando: 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
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.
Recomenda-se verificar todas as alterações feitas com o linter. Isso irá falhar o buildbot se não passar. Para verificar, execute .\make lint
Verificação de Link
O verificador de link garante que todos os links na documentação sejam resolvidos. Isso irá falhar o buildbot se não passar. Para verificar, execute .\make linkcheck
Verificação do Tamanho da Imagem
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.
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.
O Redirect Writer adicionará automaticamente arquivos renomeados/movidos ao arquivo de redirecionamento. Execute .\make 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.
O Redirect Writer garante que haja redirecionamentos válidos para todos os arquivos. Isso irá falhar o buildbot se não passar. Para verificar, execute .\make rediraffecheckdiff para verificar se todos os arquivos foram redirecionados. Além disso, pode ser necessário executar uma compilação em HTML para garantir que todos os arquivos sejam redirecionados corretamente.
Compilando em HTML
Digite o comando .\make html para gerar o conteúdo HTML. O conteúdo está localizado no diretório build/html na raiz do repositório.
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.
Digite o comando .\make latexpdf para gerar o conteúdo PDF. O PDF está localizado no diretório build/latex na raiz do repositório.
Compilando em EPUB
Digite o comando .\make epub para gerar o conteúdo EPUB. O EPUB está localizado no diretório build/epub na raiz do repositório.
Adicionando Bibliotecas de Terceiros em Python
Importante
Depois de fazer qualquer alteração as dependências de frc-docs, requirements.txt deve ser gerado novamente rodando poetry export -f requirements.txt --output source/requirements.txt --without-hashes a partir do diretório raiz.
frc-docs uses Poetry to manage its dependencies to make sure builds are reproducible.
Nota
Poetry *não* é necessária para construir e contribuir no conteúdo de frc-docs. É usado apenas para o gerenciamento de dependências.
Instalando Poetry
Ensure that Poetry is installed. Run the following command: pip install poetry.
Adicionando uma Dependência
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.
Atualizando uma Dependência de Alto Nível
Update the dependency’s version in the [tool.poetry.dependencies] section of pyproject.toml. Then, run the following command: poetry lock --no-update.