تبدیل فایل های IPYNB به HTML و استقرار خودکار در github-pages (بخش دوم)

به بخش دوم مقاله خوش اومدید. تو این بخش قراره ببینیم که چطوری میشه با استفاده از گیت هاب اکشن از اسکریپتی که تو بخش اول این مقاله نوشتیم به صورت خودکار استفاده کنیم.

نحوه عملکرد این اکشن به این شکله که شما هربار تغییراتی رو روی مخزن (repository) موردنظر پوش میکنید، چک میکنه که آیا فایل های با فرمت ipynb تغییر کردند یا خیر. اگر تغییری در اونا صورت نگرفته باشه که اتفاقی نمیوفته ولی اگه تغییر کرده باشن اسکریپتی که تو بخش اول نوشتیم رو اجرا میکنه. یعنی فایل های نوت بوک رو به فایل های HTML تبدیل میکنه و اونا رو به دایرکتوری تعیین شده برای github pages منتقل میکنه.

سرویس github actions چیه؟

هدف این سرویس اتوماتیک کردن برخی فرایندهاست، مثل تست، استقرار (deploy) و ...؛ گیت هاب اکشن رویداد محور (event-driven) هستش، یعنی زمانی که رویداد خاصی مثل پوش اتفاق بیوفته یک سری کارهایی که تعیین کردیم رو انجام میده.

اگه دوست دارید بیشتر با این سرویس آشنا بشید میتونید به داکیومنت اصلی گیت هاب اکشن مراجعه کنید.

نحوه کار github action و استقرار فایل ها در github pages
نحوه کار github action و استقرار فایل ها در github pages

اکشنی که قراره بنویسیم رو میتونین از مخزن اصلی گیت هاب ایرانی پای بردارید.

جریان کار (workflow)

برای استفاده از این ویژگی باید از یک سری قوانین پیروی کنیم. یکی از این قوانین قرار دادن فایل اکشن تو دایرکتوری ای هست که خود گیت هاب گفته. اول از همه لازمه که یک دابرکتوری به اسم github. تو مخزنمون ایجاد کنیم. حالا تو این دایرکتوری یک دایرکتوری دیگه به اسم workflows درست میکنیم. حالا تو این دایرکتوری یک فایل به اسم ipynb_docs_renderer.yml میسازیم. اسم فایل دلخواهه و قراره جلوتر ازش استفاده کنیم ولی پسوندش باید حتما yml باشه.

پس ساختار مخزن (repository) اینجوری شد:

./repository/
│
├── .github/
     ├── workflows/
         ├── ipynb_docs_renderer.yml

اکشن (action)

name: ipynb documents renderer
on:
  push:
    paths:
       - '**.ipynb'
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.8]
  steps:
     - uses: actions/checkout@v2
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
        - name: install dependencies
        run: |
          python -m pip install --upgrade pip
          python ipynb_docs_renderer.py install-dependencies
       - name: convert ipynb documents to html
       run: |
          python ipynb_docs_renderer.py render    
      - name: commit and push changes
       run: |
         python ipynb_docs_renderer.py commit-push

این محتوای فایل yml هستش که تو مرحله قبل ساختیم. خب بریم ببینیم هر قسمتش چه کاری انجام میده.

name

کاملا اختیاریه. اسمیه که تو تب actions مخزن تو گیت هاب نشون میده.

on

رویدادی که میخوایم بعد از اتفاق افتادنش job اجرا بشه رو اینجا مینویسیم. اینجا ما نوشتم push پس سر هر بار پوش شدن job اجرا میشه. ولی یک شرط دیگه هم اضافه کردیم: paths. اینجا مشخص میکنیم که اگه کدوم دایرکتوری ها یا فایل ها تغییر کردن job رو اجرا کنه. اینجا نوشتیم ipynb.** که یعنی تو هر دایرکتوری و ساب دارکتوری ای فایلی با فرمت ipynb تغییر کرد job رو اجرا کن.

jobs

تمام کارایی که قراره با هر بار اجرا شدن این اکشن انجام بشه رو اینجا مینویسیم.

build

اطلاعات سیستم عامل و نسخه پایتونی که میخوایم برای این job استفاده کنیم رو اینجا مینویسیم.

runs-on

اینجا مشخض میکنیم که از چه سیستم عاملی و چه نسخه ای از اون سیستم عامل میخوایم استفاده کنیم. ما از ubuntu-latest استفاده کردیم، یعنی آخرین نسخه سیستم عامل ابونتو. امکان انتخاب چند تا سیستم عامل هم وجود داره.

strategy

تو این بخش نسخه پایتونی که میخوایم استفاده کنیم رو مشخض کردیم. میتونید برای هر job چند تا نسخه مختلف پایتون هم در نظر بگیرید.

steps

تمامی دستوراتی که قراره اجرا بشن رو اینجا مینویسیم. هر آیتمی که اینجا بنویسیم تو یک shell جداگونه اجرا میکنه.

uses: actions/checkout@v2

اینجا گفتیم که از نسخه شماره 2 اکشن ها استفاده کن. این اکشن با دانلود کردن مخزن (repository) موردنظر، اجازه میده که کارای مختلف رو کدهای موجود تو اون مخزن (repository) انجام بدیم. همیشه از همین نسخه باید استفاده بشه (طبق اسناد موجود در سایت گیت هاب).

name: Set up Python ${{ matrix.python-version }}

اسم step ای که میخوایم اجرا کنیم رو اینجوری مشخص میکنیم. {{ matrix.python-version }} معادل نسخه پایتونی هست که تو matrix مشخص کردیم.

uses: actions/setup-python@v2

این اکشن یک محیط پایتون برامون فراهم میکنه.

with: python-version: ${{ matrix.python-version }}

مقدار متغیر python-version رو معادل نسخه پایتون استفاده شده قرار میده.

name: install dependencies

اسم step بعدی رو تعیین میکنه.

run

دستوری که میخوایم تو shell اجرا بشه رو اینجا مینویسیم. هر دستوری میتونه باشه فقط باید تو سیستم عامل انتخابی معتبر باشه.

اینجا اول pip رو نصب و آپگرید میکنیم. بعد هر بار قستمی از فایل نوشته شده در بخش اول این مقاله رو اجرا میکنیم.

تو این پست ایرانی پای دیدید که چجوری یک workflow تو گیت هاب راه بندازیم و با استفاده از اون کارای تکراری و خسته کننده مون رو به صورت خودکار انجام بدیم، تا هم تو وقت صرفه جویی کرده باشیم هم احتمال اشتباه کردن رو پایین آورده باشیم. با استفاده از این سرویسهای کاربردی گیت هاب کارای خیلی زیادی میشه انجام داد. خوبه که بلد باشید، حتما به کارتون میاد.

امیدواریم از این پست دو بخشی استفاده کافی رو برده باشید. اگه شما هم مثل ما از خوندن مطالب پایتونی لذت میبرید، خوشحال میشیم ما رو تو شبکه های اجتماعی دنبال و در صورت داشتن انتقاد و پیشنهاد ما رو ازش مطلع کنید. لایک هم یادتون نره :)

اگه با فعال سازی و نحوه استفاده از github pages مشکلی دارید، توصیه میشه به این پست اینستاگرام، ایرانی پای سر بزنید.

حمایت از ما

با دنبال کردن ما در

یا کمک مالی به مبلغ دلخواه از طریق درگاه آیدی پی میتونید از ما حمایت کنید.

وب سایت (به زودی): iranipy.ir