GitHubActions を使ってAsciiDocをPDFで出力する

はじめに

• Asciidocで書いたドキュメントを提供する方法としてGitHubActionsを使ってPDF化して提供することを業務で行った
• GitHubActionsは他のチームが書いたものを模倣して作成したため、理解できていない。次に前にやったことありますよね？と言われてもきっとできない。
  と思ったので、整理しておこうと思う。

やったことのサマリ

• GitHubのリポジトリからフォルダ/.github/workflowsを作成して、そこにYamlファイルを作成した
• Yamlファイルには、PDF出力するためのフローの定義を書いた
• リポジトリ内にscriptsフォルダを作成して、フローから呼び出しを行い実行するためのgen.shを作成した
  • gen.shでなくても、直接フローに書いても良いみたいだったが、inputファイルとするAsccidocファイルと出力するPDFファイル名をパラメータにして'asciidoctor-pdf'を実行した
• フローを定義する中でGemfileを使ったパッケージのインストールがあるため、リポジトリの直下にGemfileを作成してasciidoctor、asciidoctor-pdf、asciidoctor-pdf-cjkを定義
  • これはGemfile を使用したパッケージのインストールを参考に作成しました。
• GitHub Actions からJobを実行して、エラーになったりした内容を確認して、修正しては実行して、PDF出力できた。

実際にやった内容は以下（困ったことと対応したことも）

• GitHub Actionでは、リポジトリの配下にフォルダ作成して、Yamlファイルを配置する。

  • フォルダの作成は、【Add file】から【Create new file】を選択
    

  • ファイル名の代わりに【フォルダ名 + /】と入力するとフォルダとして認識してもらえる

    • フォルダパスを入力した後、作成したいYamlファイル名を入力して作成する
      

  • 上記の手順を実施すると、フォルダの作成と空のファイルが作成される

    • ここで一度、Commitしてからファイルを登録しても良いが、今回は作成したまま次のフロー定義を記述していく。

• 作成したYamlファイルにPDF出力するためのフロー定義を記述する

PdfOutput.yml(最初に登録した内容)

# ワークフロー名を設定する
name:  Generate PDF
# ワークフローのトリガー設定
on:
  workflow_dispatch:

# ワークフローの実行内容の定義
jobs:
  CreatePDF:          # Jobの名前
    # 実行する場所の指定
    runs-on: ubuntu-latest
    # ワークフローで実施するフローの流れ      
    steps:
      # チェックアウト
      - name: Checkout
        uses: actions/checkout@v2

      # 環境を整える、AsciiDoctorとBundlerをインストール
      - name: Install asciidoctor           # 実行時に出てくる処理の名前
        run: |
          apt-get update
          apt-get install asciidoctor -y
          gem install bundler -N
          bundle install
      - name: Generate PDF         # 実行時に出てくる処理の名前
        run: |
          chmod +x scripts/gen.sh
          scripts/gen.sh
      - name: Archive files                 # 実行時に出てくる処理の名前
        uses: actions/upload-artifact@v2    # 圧縮する
        with:
          name: MAP_PDF
          path: |
            build
          retention-days: 30       # 保存期間　：　30日間

困ったこと1

”#” でコメントを書くことができるのですが、♯（環境依存文字？）への変換がされていたりして、コンパイルが通らず、苦戦した
できるだけ、コピペとかはせずに、入力することで回避したけど、何かうまい方法があれば知りたい。。。💦

困ったこと2

Install asciidoctorを実行したら open (13: Permission denied)とエラーになり権限がないとのこと
コマンド実行する前に、sudoを付けて実行するように修正しました

PdfOutput.yml(最終的に動作確認できた内容)

# ワークフロー名を設定する
name:  Generate PDF
# ワークフローのトリガー設定
on:
  workflow_dispatch:

# ワークフローの実行内容の定義
jobs:
  CreatePDF:          # Jobの名前
    # 実行する場所の指定
    runs-on: ubuntu-latest
    # ワークフローで実施するフローの流れ      
    steps:
      # チェックアウト
      - name: Checkout
        uses: actions/checkout@v2

      # 環境を整える、AsciiDoctorとBundlerをインストール
      - name: Install asciidoctor           # 実行時に出てくる処理の名前
        run: |
          sudo apt-get update
          sudo apt-get install asciidoctor -y
          sudo gem install bundler -N
          sudo bundle install
      - name: Generate PDF         # 実行時に出てくる処理の名前
        run: |
          chmod +x scripts/gen.sh
          scripts/gen.sh
      - name: Archive files                 # 実行時に出てくる処理の名前
        uses: actions/upload-artifact@v2    # 圧縮する
        with:
          name: MAP_PDF
          path: |
            build
          retention-days: 30       # 保存期間　：　30日間

• 上記のYamlの中で呼び出すと記載したgen.shをリポジトリ直下にscriptsフォルダを作成して配置しました。
  

• gen.shの内容は、以下で作成しました。

#!/bin/sh

# PDF
bundle exec asciidoctor-pdf -a scripts=cjk -a pdf-theme=default-with-fallback-font docs/JapaneseMap.adoc -o build/Japnese-Map.pdf

困ったこと3

GitHubActionsはLinux上で動いているんですね…💦
大文字、小文字を明確に判別しているので、docs/JapaneseMap.adocファイルが存在しないと怒られ、エラーになった。
よくよく見たら、Docs/JapaneseMap.adoc だったので、以下のように修正しました。

#!/bin/sh

# PDF
bundle exec asciidoctor-pdf -a scripts=cjk -a pdf-theme=default-with-fallback-font Docs/JapaneseMap.adoc -o build/Japnese-Map.pdf

• リポジトリの直下にGemfileファイルを作成して以下の3つのパッケージをインストールできるようにします。
  • asciidoctor
  • asciidoctor-pdf
  • asciidoctor-pdf-cjk

実際に書いた内容は以下

# frozen_string_literal: true

source 'https://rubygems.org'

git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }

gem "asciidoctor"
gem "asciidoctor-pdf"
gem "asciidoctor-pdf-cjk"

• GitHub Actionsを開くとyamlファイルで定義したGenerate PDFが表示さていることを確認
  

• Generate PDFをクリックすると、イベントトリガーを選択することができます。
  　　

• Run workflowのプルダウンを選択すると、実行ボタンRun workflowが出てくるので、クリックして実行します。
  　

• 実行がうまくいくと、以下のような感じでPDFをarchiveしたファイルMAP_PDF が出来上がるので、DLとするとPDFファイルを見ることができるようになります。
  　　

まとめ

• GitHubはLinuxで動いているので、フォルダやファイルの名前、バッチ名など、大文字小文字をしっかり判別するので、作成するときには、しっかりと意識して作成しないとダメなんですね。
• Yamlファイルで使えるコメント行を意味する"#"は、環境依存文字とかにならないようにしっかり半角"#"を選択しないと実行業と判断されて処理がエラーになってしまうので、慎重にコーディングしないとダメなんですね。
• Yamlファイルを書く際、実行環境を整えるためにapt-getなどの実行をする必要があり、『これはおまじないです』って聞いていたが実際には権限が無くて、エラーになったｗ
  • sudo コマンドで権限付与して難を乗り越えたが、一般ユーザーにインストール権限がないことを意識して、環境として設定しておくのか、WorkFlowを定義する都度、コマンドとして書くかは考えないとですね。
    • 個人で使っている分には、sudoでいい気がする
• Github Actionsでの実行とは少し異なるが、一つ目の内容と同じことはasciidocを書く際にも同じことが言える
  • PDF化するにあたって、表紙となるadocファイルを準備して、複数のadocファイルを連結するためインポートを行ったり、
  • また、各adocファイルの中で、画像ファイルなど読み込んでいる。
  • Visual Studio Code(Windows環境)でドキュメントを書いているときには気にならなかったが、やはり、ファイル連結するためにShellから起動しているので、大文字小文字はしっかり判別されるので、注意が必要！