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 を使用したパッケージのインストール](https://docs.aws.amazon.com/ja_jp/elasticbeanstalk/latest/dg/ruby-platform-gemfile.html)を参考に作成しました。
- `GitHub Actions` から`Job`を実行して、エラーになったりした内容を確認して、修正しては実行して、PDF出力できた。

# 実際にやった内容は以下（困ったことと対応したことも）
- `GitHub Action`では、リポジトリの配下にフォルダ作成して、Yamlファイルを配置する。
    - フォルダの作成は、【Add file】から【Create new file】を選択
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/876a3d91-7857-5ac3-9cac-b2cd518411b5.png)

    - ファイル名の代わりに【フォルダ名 + /】と入力するとフォルダとして認識してもらえる
        - フォルダパスを入力した後、作成したいYamlファイル名を入力して作成する
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/01bb60f7-c136-ac92-46cd-f4e7aa97c4b7.png)

    - 上記の手順を実施すると、フォルダの作成と空のファイルが作成される
        - ここで一度、Commitしてからファイルを登録しても良いが、今回は作成したまま次のフロー定義を記述していく。
        
- 作成したYamlファイルにPDF出力するためのフロー定義を記述する
<details>
<summary>PdfOutput.yml(最初に登録した内容)</summary>

``` 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日間

```
</details>

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

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

<details>
<summary>PdfOutput.yml(最終的に動作確認できた内容)</summary>

``` 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日間

```
</details>


- 上記のYamlの中で呼び出すと記載した`gen.sh`をリポジトリ直下に`scripts`フォルダを作成して配置しました。
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/7dfafca5-9135-f3a9-a757-02eeef27d644.png)

- `gen.sh`の内容は、以下で作成しました。
``` Shell
#!/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` だったので、以下のように修正しました。


``` Shell
#!/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`

実際に書いた内容は以下
``` Gemfile
# 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`が表示さていることを確認
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/75ccc2c9-a18b-be44-7eef-cad1d6303120.png)

- `Generate PDF`をクリックすると、イベントトリガーを選択することができます。
　　![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/318ee157-7e34-4d8e-c0f7-42d6631b2857.png)

- `Run workflow`のプルダウンを選択すると、実行ボタン`Run workflow`が出てくるので、クリックして実行します。
　 ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/83cb7c3b-7378-27a4-d235-fb5f9b9f2c21.png)

- 実行がうまくいくと、以下のような感じでPDFをarchiveしたファイル`MAP_PDF` が出来上がるので、DLとするとPDFファイルを見ることができるようになります。
　　![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/7d523628-c371-3b5b-061c-ad75ed47419d.png)


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