Derleme Yapısı
Bu belge, frc-docs sitesinin HTML, PDF ve EPUB sürümlerinin nasıl oluşturulacağı hakkında bilgiler içerir. frc-docs, dokümantasyon oluşturucu olarak Sphinx’i kullanır. Bu belge ayrıca `Git <https://git-scm.com/>” __ ve konsol komutları hakkında temel bilgiye sahip olduğunuzu varsayar.
Gereksinimler
Git ‘in kurulu olduğundan ve frc-docs deposunun git clone https://github.com/wpilibsuite/frc-docs.git
kullanılarak klonlandığından emin olun. ``.
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
Not
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’u yüklerken ** Add Python to PATH** seçimini yaparak sistem PATH ‘inize eklendiğinden emin olun.
Python kurulduktan sonra Powershell’i açın. Ardından frc-docs dizinine gidin. Aşağıdaki komutu çalıştırın: 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
Derleme
Bir Powershell Penceresi veya terminali açın ve klonlanan frc-docs dizinine gidin.
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 Check
Not
Lint Check, satır sonlarıyla ilgili bir hata nedeniyle Windows’ta satır sonlarını kontrol etmeyecektir. Daha fazla bilgi için `bu soruna <https://bugs.launchpad.net/doc8/+bug/1756704>`__bakın.
Linter ile yaptığınız değişiklikleri kontrol etmeniz önerilir. Bu başarılı olmazsa buildbot’ta başarısız olacaktır. Kontrol etmek için . \ Make lint
komutunu çalıştırın.
Link Check - Bağlantı Denetleme
Bağlantı denetleyicisi, belgelerdeki tüm bağlantıların çözümlendiğinden emin olur. Bu başarılı olmazsa buildbot’ta başarısız olacaktır. Kontrol etmek için . \ Make linkcheck
komutunu çalıştırın.
Resim boyutu denetimi
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.
Yönlendirme Kontrolü
Taşınan veya yeniden adlandırılan dosyaların yeni konumları (veya 404 ile değiştirilmiş) `` kaynak ‘’ içindeki `` redirects.txt ‘’ dosyasında bulunmalıdır.
Yönlendirme yazıcısı, yeniden adlandırılmış / taşınmış dosyaları yeniden yönlendirmeler dosyasına otomatik olarak ekleyecektir. Çalıştır .\make rediraffewritediff
.
Not
bir dosya hem taşınırsa hem de önemli ölçüde değiştirilirse, yeniden yönlendirme yazıcısı onu `` redirects.txt ‘’ dosyasına eklemeyecek ve redirects.txt
dosyasının manuel olarak güncellenmesi gerekecektir.
Yeniden yönlendirme denetleyicisi, tüm dosyalar için geçerli yeniden yönlendirmeler olduğundan emin olur. Bu **, başarılı olmazsa buildbot’ta başarısız olur **. Kontrol etmek için, tüm dosyaların yeniden yönlendirildiğini doğrulamak için .\make rediraffecheckdiff
komutunu çalıştırın. Ek olarak, tüm dosyaların düzgün bir şekilde yeniden yönlendirilmesini sağlamak için bir HTML yapısının çalıştırılması gerekebilir.
HTML Derleme
HTML içeriği oluşturmak için .\make html
komutunu yazın. İçerik depo kök dizinindeki build/html
dizininde bulunur.
PDF Oluşturma
Uyarı
Windows üzerinde PDF derlemesinin SVG içeriği için bozuk görüntülere neden olabileceğini lütfen unutmayın. Bunun nedeni, Windows’ta librsvg2-bin desteğinin olmamasıdır.
PDF içeriği oluşturmak için .\make Latekspdf
komutunu yazın. PDF, arşivin kök dizinindeki build/latex
dizininde bulunur.
EPUB Derlemek
EPUB içeriği oluşturmak için .\ Make epub
komutunu yazın. EPUB, deponun kök dizinindeki build/epub
dizininde bulunur.
Python 3. Parti Kütüphaneleri ekleme
Önemli
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.
Not
Poetry is not required to build and contribute to frc-docs content. It is only used for dependency management.
Poetry Kurulumu
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
.