ستكون المادة مفيدة للمبتدئين وأولئك الذين يرغبون في رفع CI / CD بسرعة لمادة اللاتكس باستخدام أدوات GitHub المدمجة.
المقدمة
أثناء تصفح المستودع باستخدام سيرتي الذاتية في اليوم الآخر (أجعلها في مادة اللاتكس ، لحسن الحظ ، هناك العديد من القوالب ) ، اعتقدت أنه سيكون من الجيد تنظيم نوع من المكان الفردي حيث يكمن الإصدار الحالي من المستند دائمًا.
كانت المتطلبات الأساسية بسيطة:
- بأقل جهد لرفع الموقع بالإصدارات ؛
- جعل تحديثات المحتوى على الموقع تلقائية.
تم رسم حل على شكل خط أنابيب في رأسي:
- دفع الالتزام بـ GitHub ؛
- بناء ملفات .tex في CI / CD ؛
- تقديم ملفات PDF التي تم جمعها إلى إصدارات GitHub ؛
- تحديث ملفات pdf على موقع بطاقة العمل.
في هذه المقالة ، سوف نلقي نظرة فاحصة على كل خطوة. سيكون الموقع صفحات GitHub. بالنسبة إلى CI / CD ، سنستخدم إجراءات GitHub.
نحن نحتاج:
- حساب جيثب
- أدوات تجميع LaTeX ؛
- أي محرر نصوص (أنا أستخدم VIM تم تكوينه من أجل اللاتكس ) ؛
اذهب!
ربط إجراءات جيثب
هنا ، يمكن تنفيذ جميع الإجراءات من الموقع دون اللجوء إلى وحدة التحكم.
انتقل إلى "الإجراءات" (مسطر باللون الأحمر).
والعثور على بطاقة "سير العمل البسيط" هناك ، حيث نضغط على الزر "إعداد سير العمل هذا"
سيتم فتح محرر بقالب سير العمل أمامنا. يجدر الخوض في هذه النقطة بمزيد من التفصيل.
يعمل GitHub Actions مع مهام سير العمل الموضحة في ملفات منفصلة. يتكون كل سير عمل من:
- الاسم (القسم
name: …) ؛ - شروط البدء (قسم
on: …) ؛ - قائمة المهام التي يتعين القيام بها (قسم
jobs: …)
تتكون كل وظيفة أيضًا من أجزاء أصغر تسمى الخطوة . كل خطوة هي فعل ذري (يتم إجراؤه مرة واحدة). في هذه الحالة، خطوة لها اسم خاص به (
name: …) وقائمة من الأوامر ( run: …)، ويمكن أيضا أن تستخدم الجاهزة العمل ( uses: …) من مطوري الطرف الثالث. إجراءات
الطرف الثالث هي أقوى جزء في إجراءات GitHub. ويمكن أن تفعل أشياء كثيرة: تثبيت JDK ، اختبارات الثعبان تشغيل في توكس، وأكثر من ذلك. في هذا البرنامج التعليمي ، سنستخدم xu-cheng / latex-action @ v2 لتجميع مادة اللاتكس (لم تكن هناك مشاكل مع السيريلية) والإجراءات / upload-artifact @ v2 لتحميل القطع الأثرية.
دعنا نعود إلى محررنا. يمكن تصحيح النموذج المقترح ، وإعادته إلى النموذج:
name: Build and deploy latex sources to GitHub Pages
on: push
jobs:
build:
# , . ubuntu
runs-on: ubuntu-latest
steps:
# action,
- uses: actions/checkout@v2
#
- name: Build document
uses: xu-cheng/latex-action@v2
with:
# ,
root_file: main.tex
# .
working_directory: latex_sources/
# , (latexmk)
# -jobname=<name>
args: -jobname=my_doc -pdf -file-line-error -halt-on-error -interaction=nonstopmode
compiler: latexmk
# pdf-
- name: Upload pdf document
uses: actions/upload-artifact@v2
with:
#
name: my_doc
# pdf. «*», «**»
# <working_directory>/<jobname>.pdf
path: latex_sources/my_doc.pdf
احفظه في ملف ، واختر أي اسم ملف (يمكنك استخدام latex.yml). بعد الالتزام بإنشاء الملف لمحرري الويب ، يجب أن ينتقل البناء الأول إلى إجراءات GitHub ، ونتيجة لذلك ستظهر قطعة أثرية - ملف pdf المترجم.
الصيحة! الآن يمكنك البدء في الإفراج.
إعداد الإصدارات التلقائية
يتميز نظام الإصدار في GitHub بخصوصية واحدة: يرتبط الإصدار دائمًا بالتزام بعلامة. لذلك ، لدينا خياران:
- إضافة علامات يدويًا إلى تلك الالتزامات التي نريد جمع ملفات pdf وإصدارها ؛
- قم تلقائيًا بتمييز جميع الالتزامات وحررها.
بالنسبة لي ، بدا الخيار الثاني أكثر ملاءمة. عادةً ما ألتزم وأدفع عندما يكتمل العمل (إما منطقيًا أو لهذا اليوم). لذلك ، سأتحدث عنه في المستقبل.
لإنشاء الإصدار ، سنستخدم الإجراء Actions / create-release @ v1 ولتحميل ملف pdf إلى الإصدار الذي تم إنشاؤه (نعم ، يتم تحميله بشكل منفصل) سنستخدم الإجراءات / upload-release-asset @ v1 .
دعنا نضيف وظيفة جديدة :
deploy:
runs-on: ubuntu-latest
# master. ,
if: github.ref == 'refs/heads/master'
# job. .
needs: [build]
steps:
# , bash-
- name: Variables
# id : step
id: vars
# echo ${{ steps.<step_id>.outputs.<variable_name> }}
# | — yaml. ,
run: |
echo «::set-output name=date::$(date +'%Y-%m-%d')»
echo «::set-output name=sha8::$(echo ${GITHUB_SHA} | cut -c1-8)»
- name: Download artifacts
uses: actions/download-artifact@v2
with:
# , upload-artifact
name: my_doc
- name: Create Release
uses: actions/create-release@v1
id: create_release
env:
# ., GITHUB_TOKEN
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions
with:
# step id=vars (. ).
# “my_doc-< >-< 8 sha >
tag_name: my_doc-${{ steps.vars.outputs.date }}-${{ steps.vars.outputs.sha8 }}
# ,
release_name: My Actions document (version ${{ steps.vars.outputs.date }})
# , false
draft: false
prerelease: false
# step
- name: Upload pdf asset
uses: actions/upload-release-asset@v1
env:
#
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
# step id=create_release upload_url —
upload_url: ${{ steps.create_release.outputs.upload_url }}
# latex_sources, download-artifacts
asset_path: ./my_doc.pdf
# ,
asset_name: my_asset_name.pdf
asset_content_type: application/pdf
أضف إلى ملف سير العمل ، وقم بتنفيذ التغييرات. انتقل إلى الإجراءات وتأكد من إضافة خطوة أخرى:
في الوقت نفسه ، ظهر ملف pdf المترجم أيضًا في الإصدارات.
الشيء الوحيد المتبقي هو تحميله على الموقع.
إحضار صفحات جيثب
يوفر GitHub القدرة لكل مشروع على إنشاء صفحة ويب ويوفر استضافة مجانية لها. لكن ليس عليك معرفة JS / CSS / HTML لتكتب شيئًا يستحق العناء! من خارج الصندوق ، تقدم الخدمة العديد من القوالب الجميلة التي تحل مشكلة التخطيط تمامًا. كل ما عليك فعله هو ملء مستند Markdown ، ويقوم النظام بالباقي.
نذهب إلى قسم "الإعدادات" في المستودع وفي علامة التبويب "الخيارات" (التي تفتح أولاً افتراضيًا) مرر لأسفل إلى "صفحات GitHub".
هنا نختار الفرع الرئيسي كمصدر ، و / docs كمجلد (يمكنك أيضًا استخدام / الجذر ، لكنني أفضل الاحتفاظ بالحد الأدنى من عدد الملفات في جذر المشروع). انقر فوق "حفظ".
يفتح زر "منتقي القوالب" معرضًا للقوالب ، حيث يمكن طعن كل منها وعرضها وتحديدها بالنقر فوق الزر الأخضر "تحديد سمة".
بعد اختيار سمة ، سيتم طرحنا في محرر الويب ، حيث يُقترح تحرير ملف Markdown ، والذي سيصبح بعد ذلك الموقع. يمكنك هنا وصف كل ما تتمناه قلبك: من عرض تقديمي بسيط لنفسك إلى أهداف المستند وخصائص العمل.
بمجرد أن تشعر بالرضا عن المحتوى ، قم بإجراء تغييراتك.
اين صفحتي؟
دائمًا ما يتم تخزين رابط الصفحة المجمعة في الإعدادات -> صفحات GitHub. من الأفضل تسجيله في موقع الويب الخاص بالمستودع (الترس الموجود بجوار حقل "حول" في الصفحة الرئيسية) حتى لا يفقده.
تنزيل أحدث إصدار
هناك حيلة صغيرة: يمكن دائمًا الرجوع إلى أحدث إصدار وجميع ملفاته عن طريق استبدال علامة الالتزام في عنوان URL بـ "الأحدث". في مثالنا ، للحصول على ملف my_asset_name.pdf من أحدث إصدار ، نحتاج إلى إدراج ارتباط
https://github.com/<your_username>/<repo_name>/releases/latest/download/my_asset_name.pdf.
في حالتي كان: https://github.com/alekseik1/github_actions_latex_template/releases/latest/download/my_asset_name.pdf .
بعد هذه الخطوات ، ترتبط صفحات GitHub دائمًا بأحدث إصدار.
النتيجة
قمنا بإعداد إجراءات GitHub لإنشاء ملف pdf تلقائيًا ، ووضعه في الإصدار ، وإنشاء موقع على صفحات GitHub يحتوي على أحدث إصدار. يمكن العثور على النسخة النهائية من المشروع هنا .
شكرآ لك على أهتمامك!