この資料は、初心者や、組み込みのGitHubツールを使用してラテックス用のCI / CDをすばやく作成したい人に役立ちます。
前書き
先日、CVでリポジトリを閲覧しているときに（私はラテックスで作成しましたが、幸いなことに多くのテンプレートがあります）、ドキュメントの現在のバージョンが常に存在するある種の単一の場所を整理するとよいと思いました。
基本的な要件は単純でした。
- リリースでサイトを立ち上げるための最小限の労力で。
- サイトのコンテンツの更新を自動化します。
パイプラインの形での解決策が私の頭の中に描かれました：
- GitHubにコミットをプッシュします。
- .texファイルをCI / CDにビルドします。
- 収集したpdfをGitHubリリースに送信する。
- 名刺サイトのpdfファイルを更新しています。
この記事では、各ステップを詳しく見ていきます。サイトはGitHubページになります。CI / CDの場合、GitHubアクションを使用します。
必要なもの：
- GitHubアカウント;
- LaTeXコンパイルツール。
- 任意のテキストエディタ（ラテックス用に構成されたVIMを使用しています）;
行く！
GitHubアクションの接続
ここでは、コンソールに頼ることなく、サイトからすべてのアクションを実行できます。
「アクション」（赤で下線が引かれている）に移動します。
そこにある「シンプルワークフロー」カードを見つけて、「このワークフローを設定」ボタンを押します。
ワークフローテンプレートを備えたエディターが目の前に開きます。この点についてさらに詳しく説明する価値があります。
GitHubアクションは、個別のファイルで説明されているワークフローで機能します。各ワークフローは次のもので構成されます。
- 名前（セクション
name: …）; - 開始条件（セクション
on: …）; - 実行するタスクのリスト（セクション
jobs: …）
各ジョブは、stepと呼ばれる小さなチャンクでも構成されます。各ステップはアトミックアクションです（一度に実行されます）。この場合、stepには独自の名前（
name: …）とコマンドのリスト（）があり、サードパーティの開発者run: …による既成のアクション（uses: …）を使用することもできます。
サードパーティのアクションは、GitHubアクションの最も強力な部分です。彼らは多くのことを行うことができます：JDKをインストールし、TOXにPythonのテストを実行し、そしてより多くの。このチュートリアルでは、xu-cheng / latex-action @ v2を使用してラテックスをコンパイルし（Cyrillicには問題はありませんでした）、アクション/アップロード-アーティファクト@ 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を使用できます）。ファイルの作成をWebエディターにコミットした後、最初のビルドはGitHubアクションに移動する必要があります。その結果、アーティファクト（コンパイルされたpdf）が表示されます。
やったー！これで、リリースを開始できます。
自動リリースの設定
GitHubのリリースシステムには、1つの特徴があります。リリースは、常にタグ付きのコミットに関連付けられています。したがって、2つのオプションがあります。
- pdfファイルを収集してリリースするコミットにタグを手動で追加します。
- すべてのコミットに自動的にタグを付けて解放します。
私にとって、2番目のオプションの方が便利に思えました。私は通常、作業が完了したときに（論理的にまたは今日のために）コミットしてプッシュします。したがって、将来的には彼について話します。
リリースを作成するには、actions / create-release @ v1アクションを使用し、作成されたリリースにpdfファイルをアップロードします（はい、個別にアップロードされます）。actions/ 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
ワークフローファイルに追加し、変更をコミットします。[アクション]に移動して、もう1つのステップが追加されていることを確認します。
同時に、コンパイルされたpdfもリリースに登場しました。
残っているのはそれをサイトにアップロードすることだけです。
GitHubページを表示する
GitHubは、各プロジェクトがWebページを作成する機能を提供し、そのための無料のホスティングを提供します。しかし、価値のあるものを書くためにJS / CSS / HTMLを知る必要はありません！箱から出して、サービスはレイアウトの問題を完全に解決するいくつかのきれいなテンプレートを提供します。あなたがする必要があるのはマークダウン文書に記入することだけです、そしてシステムは残りをします。
リポジトリの[設定]セクションに移動し、[オプション]タブ（デフォルトで最初に開かれます）で、[GitHubページ]まで下にスクロールします。
ここでは、ソースとしてmasterブランチを選択し、フォルダーとして/ docsを選択します（/ rootを使用することもできますが、プロジェクトルートに最小数のファイルを保持することをお勧めします）。「保存」をクリックします。
[テーマの選択]ボタンをクリックすると、テンプレートのギャラリーが開き、緑色の[テーマの選択]ボタンをクリックして、テンプレートを突いたり、表示したり、選択したりできます。
テーマを選択すると、Webエディターに移動し、Markdownファイルを編集することが提案されます。Markdownファイルがサイトになります。ここでは、あなた自身の簡単なプレゼンテーションから、ドキュメントの目標や作品の特徴まで、あなたの心が望むすべてを説明することができます。
コンテンツに満足したら、変更をコミットします。
私のページはどこにありますか？
アセンブルされたページへのリンクは、常に[設定]-> [GitHubページ]に保存されます。紛失しないように、リポジトリのウェブサイト（メインページの「About」フィールドの横にあるギア）に登録することをお勧めします。
最新リリースのダウンロード
ちょっとしたコツがあります。URLのcommitタグを「latest」に置き換えることで、最新リリースとそのすべてのファイルをいつでも参照できます。この例では、最新リリースから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ページは常に最新リリースにリンクします。
結果
pdfファイルを自動的に作成してリリースするようにGitHubActionsを設定し、最新バージョンを含むサイトをGitHubページに表示しました。プロジェクトの最終バージョンはここにあります。
清聴ありがとうございました！