GitHub Actionsを使って気軽にAsciiDocを出力しよう(1) | cloud.config Tech Blog

はじめに

AsciiDocを利用したいけど環境構築は面倒くさい。
エンジニアが気軽に出版レベルのドキュメントを作成したりWikiより管理の容易なナレッジを作成するのに役立つAsciiDoc。
その面倒な環境構築をほとんど抜きにしてGitHubでホスティングするだけでHTML作成まで自動化する方法を紹介します。

AsciiDocについて

AsciiDocについては前回の記事にて紹介させていただきました。こちらの記事をご参照いただけると嬉しいです。

AsciiDocを利用してエンジニアのナレッジを上手に集約しよう

GitHub Actionsとは

GitHub Actionsはコードを保存するリポジトリと同じ場所でソフトウェア開発のワークフローを自動化する機能です。
従来からCI/CD環境をJenkins等で構築されている方も多いかと思いますが、小規模な開発では構築の負担が大きかったり、複数の環境を管理する必要に追われ開発の時間を奪われてしまうことがありました。
GitHub Actionsは自動化したワークフローを無料で利用できるサービスです。
ワークフローにはコンテナイメージを利用できるため、非常に柔軟性が高いCI/CD環境を構築可能です。

実際に簡単なHTMLを出力してみよう

ここからは実際の.adocファイルを利用しHTMLを出力する方法をご紹介します。
今回はアクションの詳しい内容やAsciiDocのオプションについては割愛し、簡単なHTMLを出力のみ行います。

GitHubリポジトリを作成しよう

GitHubに新たなリポジトリを作成します。
通常のリポジトリ作成作業になりますが、READMEの作成は行いません。
手順に不安がある方は、以下のマニュアルに沿って作成し、
『5 [Initialize this repository with a README] を選択します。』を選択せず飛ばしていただき、
『6 [Create repository] をクリックします。』までの作業を行います。

※ 最初の変更をコミットする以降の作業はまだ行わないでください。

GitHub.comでリポジトリを作成する

ワークフローを作成しよう

一番簡単なワークフローを作成し出力を試してみましょう。

※今回は初めてアクションを利用される方向けにGUIでの説明にしますが、
workflowの作成方法をご存知の方は『.github/workflows』を作成していただいても構いません。

リポジトリーページのタブでActionsを選びます。
Actionが設定されていないリポジトリでは『Get started with GitHub Actions』ページが表示されます。
『Simple workflow』の『Set up this workflow』ボタンを押します。
ファイル名を『blank.yml』から『asciidoc.yml』に変更します。
『Edit new file』で表示されているYAMLの内容を以下の「ワークフロー[asciidoc.yml]のサンプル」に書き換えます。
『Start commit』を押下しコミットします。

ワークフロー[asciidoc.yml]のサンプル

# This is a AsciiDoctor workflow to help you get started with Actions
name: CI

# Controls when the action will run. Triggers the workflow on push 
# events but only for the master branch
on:
  push:
    branches: [ master ]
    
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "asciidoctor_job"
  asciidoctor_job:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest
    name: Build AsciiDoctor
    steps:
    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
    - name: Check out code
      uses: actions/checkout@v2
    # Output command using asciidoctor-action
    - name: Build AsciiDoc step
      id: documents
      uses: Analog-inc/asciidoctor-action@master
      with:
        shellcommand: "asciidoctor README.adoc" 
    # Use the output from the documents step
    - name: Save AsciiDoc step
      uses: actions/upload-artifact@v1
      with:
        name: Output-document
        path: ./README.html

adocファイルを作成しよう

リポジトリのルートディレクトリ(masterブランチ)に「README.adoc」ファイルを作成します。
もし同一階層に『README.md』が存在する場合は削除して進めてください。
今回は以下「Asciidoc[README.adoc]のサンプル」の内容で記載してみましょう。

※以下の手順はGUIで気軽にお試ししたい方の手順です。環境が手元にある方はローカルで作成しcommitしてください。

リポジトリーページのルートディレクトリ(masterブランチ)を開きます。
『Create new file』を押下します。
『Simple workflow』の『Set up this workflow』ボタンを押します。
ファイル名を『README.adoc』に変更します。
『Edit new file』の内容を以下の「AsciiDoc[README.adoc]のサンプル」に書き換えます。
『Commit new file』から編集結果をコミットします。

AsciiDoc[README.adoc]のサンプル

AsciiDocサンプルのREADMEです。 +
index.adocにインクルードされる想定で記載されています。

=== ドキュメントビルドのステータス

image::https://github.com/Analog-inc/asciidoctor-action-sample/workflows/CI/badge.svg[StatusBatch] 
上記バッチは「link:https://github.com/Analog-inc/asciidoctor-action-sample/actions?query=workflow%3ACI[Analog-inc/asciidoctor-action-sample]」で最後にPushした際にアクションの状態を表します。（HTMLでは現在の状態、PDFでは一つ前の状態になります。） +
また、HTML出力ではプライベートリポジトリのステータスはログイン状態でしか取得できません。 +
バッチは以下のフォーマットで表示することが可能です。

  image::https://github.com/{github_id}/{repository}/workflows/{workflow_name}/badge.svg?branch={branch_name}[StatusBatch]


== 注意事項
ドキュメントの記述方法のサンプルです。

=== 記述方法
本ドキュメントはasciidoc形式で記述します。 +
記載方法の詳細は以下のリンクを参照して記載をお願いします。 +
link:https://takumon.github.io/asciidoc-syntax-quick-reference-japanese-translation/[Asciidoctor 文法クイックリファレンス(日本語訳)]

==== 記述時の注意事項

===== セクションタイトルのレベルについて

asciidocはヘッダー(見出し)の扱いが厳格な文書形式です。 +
また多くの人が同時に修正しやすくGitでのマージ等が低コストで行えるように、
レベル1のヘッダーごとにインクルードによるファイルの分割を行ってください。 +
また、分割したファイルではレベル2以降のヘッダーを利用し文書の構造化に努めてください。


.index.adoc
====
これはindex.adocのサンプルです。
[listing]
....
  = サンプルドキュメント (レベル0)
  [[README]]
  == 本ドキュメントについて (レベル1)
  include::README.adoc[]
....
====


.README.adoc
====
これはREADME.adocのサンプルです。
[listing]
....
  === 方針(レベル2)
  本ドキュメントはAsciidocのビルドサンプルとして利用します。
....
====

adocファイルをPushしよう

ローカルで「README.adoc」を編集した場合はPushしてください。
Webのリポジトリーページでファイルを作成・編集した場合はCommitのみとなります。
リポジトリーページのルートディレクトリ(masterブランチ)を開くとREADMEがプレビューされていることがわかります。

出力内容を確認しよう

特にAsciiDocを出力する操作は行っていませんが、
上記の(ワークフローを作成してからREADME.adocファイルをPushする)手順で作業を行えば自動的にワークフローは実行されているはずです。
実行結果の確認として「README.adoc」から出力したHTMLを以下の手順で確認します。

リポジトリーページのタブでActionsを選びます。
左ペインの『Workflows』から『CI』に進みます。
最後のコミットを選択すると。
『Artifacts』に『Output-document』が表示されています。
『Output-document』を押下しファイルをダウンロードします。
ダウンロードされた『Output-document.zip』を解凍します。
解凍後に『README.html』をブラウザで確認します。

いかがでしょうか？
『README.html』は出力できましたでしょうか？

まとめ

今回はGitHub Actionsを利用するとPushするだけで簡単にAsciiDocが出力できる方法を紹介させていただきました。
GitHubでは昨年から無料ユーザーも無制限にプライベートリポジトリを使えるようになり、GitHub Actionsも無料で利用できるためドキュメントもリポジトリで管理し出力できる環境は非常に魅力的な選択肢だと考えます。

次回は今回利用したアクションの説明をします。

GitHub Actionsを使って気軽にAsciiDocを出力しよう(2)