הנחיות בנייה
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.
דרישות מקדימות
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
הערה
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 נמצא ב-Path שלכם על ידי סימון 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
בנייה
פתחו חלון Powershell או Terminal ונווטו לתקיית 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
הערה
Lint Check will not check line endings on Windows due to a bug with line endings. See this issue for more information.
מומלץ לבדוק את כל השינויים שתבצע עם ה-linter. זה יכשיל את ה-buildbot אם הוא לא יעבור. כדי לבדוק, הרץ: .\make lint
בדיקת קישורים
בדיקת הקישורים תוודא כי כל הקישורים שבתיעוד קיימים. ה-buildbot יכשל אם בדיקה זו לא תעבור. כדי לבדוק, הריצו .\make linkcheck
בדיקות גודל התמונות
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.
בדיקת הפניות
קבצים שהועברו או ששמם שונה חייב להיות מיקומם החדש (או הוחלף ב-404) בקובץ redirects.txt
ב``source``.
The redirect writer will automatically add renamed/moved files to the redirects file. Run .\make rediraffewritediff
.
הערה
if a file is both moved and substantially changed, the redirect writer will not add it to the redirects.txt
file, and the redirects.txt
file will need to be manually updated.
The redirect checker makes sure that there are valid redirects for all files. This will fail the buildbot if it does not pass. To check, run .\make rediraffecheckdiff
to verify all files are redirected. Additionally, an HTML build may need to be ran to ensure that all files redirect properly.
בניית HTML
הריצו את הפקודה .\make html
כדי ליצור תוכן HTML. התוכן בתקיית build/html
בשורש ה-Repository.
בניית PDF
אזהרה
Please note that PDF build on Windows may result in distorted images for SVG content. This is due to a lack of librsvg2-bin support on Windows.
Type the command .\make latexpdf
to generate PDF content. The PDF is located in the build/latex
directory at the root of the repository.
בניית EPUB
Type the command .\make epub
to generate EPUB content. The EPUB is located in the build/epub
directory at the root of the repository.
Adding Python Third-Party libraries
חשוב
After modifying frc-docs dependencies in any way, requirements.txt
must be regenerated by running poetry export -f requirements.txt --output source/requirements.txt --without-hashes
from the root of the repo.
frc-docs uses Poetry to manage its dependencies to make sure builds are reproducible.
הערה
poetry לא נדרשת כדי לבנות ולתרום לתוכן frc-docs. הוא משמש רק לניהול תלויות.
התקנת Poetry
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
.