הנחיות בנייה#

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

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

וודאו כי Git מותקן וה-repository של frc-docs משוכפל באמצעות 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.

Python 3.9
Perl
MiKTeX (דרוש רק עבור בניית PDF)
rsvg-convert (Only needed for PDF builds)

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

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

מומלץ לבדוק את כל השינויים שתבצע עם ה-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.

עדכון תלות נסתרת#

Run the following command: poetry lock.