הנחיות בנייה

מסמך זה מכיל מידע כיצד לבנות את גרסאות ה-HTML, PDF ו-EPUB של אתר frc-docs. frc-docs משתמש ב-Sphinx כמייצר התיעוד. מסמך זה מניח שיש לך ידע בסיסי בפקודות Git ופקודות המסוף.

דרישות מקדימות

Ensure that Git is installed and that the frc-docs repository is cloned by using git clone https://github.com/wpilibsuite/frc-docs.git.

Windows

הערה

The majority of MikTeX packages are not required for building HTML, additional packages may be required for building PDF and EPUB.

ודאו כי Python נמצא ב-Path שלכם על ידי סימון Add Python to PATH בעת התקנת Python.

Showing where to click the box to add Python to PATH.

לאחר התקנת 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: mpm --verbose --require=@miktex-packages.txt

Lastly, you need to install rsvg-convert by running the scripts/install-rsvg-convert.ps1 script in powershell. This requires administrator access.

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 לא תבדוק סיומי השורות ב-Windows בגלל באג. ראו Issue זה למידע נוסף.

It’s encouraged to check any changes you make with the linter. This will fail the buildbot if it does not pass. To check, run .\make lint

בדיקות גודל התמונות

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.

בדיקת הפניות

Files that have been moved or renamed must have their new location (or replaced with 404) in the redirects.txt file in 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 is not required to build and contribute to frc-docs content. It is only used for dependency management.

Installing Poetry

Ensure that Poetry is installed. Run the following command: pip install poetry

Adding a Dependency

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

Updating a Top-Level Dependency

Update the dependency’s version in the [tool.poetry.dependencies] section of pyproject.toml. Then, run the following command: poetry lock --no-update

Updating Hidden Dependencies

Run the following command: poetry lock