🐹

mdocで書いたScalaドキュメントをHonkitとGitHub Actionsを使ってGitHub Pagesに自動デプロイする

2021/03/25に公開

Scala

Scala のプロジェクトのドキュメントを mdoc で書いて、Honkit と GitHub Pages でドキュメントを公開し、GitHub Actions でデプロイを自動化する、までをやってみました。

サンプルコード

本記事で作成したサンプルコードです。

サンプルコードは下記の GitHub Pages にデプロイされています。

プロジェクトの作成

まず、ベースとなる Scala プロジェクトを作成します。

ドキュメントを作りたい既存のプロジェクトがあれば、そのプロジェクトを用いてください。

% sbt new sbt/scala-seed.g8
[info] welcome to sbt 1.3.13 (Oracle Corporation Java 10.0.1)
[info] loading settings for project global-plugins from idea.sbt ...
[info] loading global plugins from /Users/tomoki/.sbt/1.0/plugins
[info] set current project to scala (in build file:/Users/tomoki/src/scala/)
[info] set current project to scala (in build file:/Users/tomoki/src/scala/)

A minimal Scala project.

name [Scala Seed Project]: honkit-seed

Template applied in /Users/XXX/src/scala/./honkit-seed

mdoc で Scala プロジェクトのドキュメントを書く

プロジェクトのドキュメントをそのまま Markdown で書くのもいいですが、Scala のドキュメントの場合 mdoc を使うと便利です。

これを使うと、以下のような Markdown ファイルを作成したとき

sbt mdoc のようなコマンドを実行すると式の評価結果が表示されます。

通常のコンパイルと同様のエラーを出してくれます。REPL で実行したコードを貼り付ける、のような作業をしなくて良いので、重宝しています。

mdoc のインストール

mdoc は、sbt のプラグインです。早速インストールしてみましょう。

最新のインストール方法は公式ドキュメントをご確認ください。 project/plugins.sbt ファイルにプラグインを追加し build.sbt に設定を追加すれば完了です。

project/plugins.sbt

addSbtPlugin("org.scalameta" % "sbt-mdoc" % "2.2.18" )

本サンプルプロジェクトでは、 docs ディレクトリを一つのプロジェクトとし、 docs/src/main にドキュメントを作っていくことにします。docs プロジェクトに MdocPlugin を有効化して、作業ディレクトリ (mdocIn) に docs/src/main を指定し、コンパイル後のファイル (mdocOut) を docs/mdoc に置くよう指定しています。

build.sbt

lazy val docs = (project in file("docs"))
  .settings(name := "docs-seed")
  .enablePlugins(MdocPlugin)
  .settings(mdocIn := file("docs/src/main"))
  .settings(mdocOut := file("docs/mdoc"))

はじめての mdoc

簡単なドキュメントを作ってみましょう。

以下の内容で docs/src/main/README.md を作成します。

そして、sbt コンソール上の docs プロジェクトにて mdoc コマンドを実行します。

% sbt docs/mdoc

すると、docs/mdoc/README.md というファイルが生成されているかと思います。

内容は次のように、式の評価結果が表示されているのではないでしょうか。

Honkit で Markdown ファイルから静的サイトを生成する

続いて、mdoc で書いた Markdown ファイル群を、Honkit を使って静的サイトにします。

Honkit は、現在開発が終了している OSS の GitBook の後継で、Markdown ファイルから HTML, PDF, EPUB などのファイルを生成できます。

Honkit のインストール

Honkit をインストールするには NodeJS 10 以上が必要です。まずはプロジェクトを初期化します。

% yarn init

設定は適当にしちゃってください。次に、プロジェクトにパッケージを追加しましょう。

% yarn add honkit --dev

すると、package.json が以下のようになっているかと思います。

package.json

{
  "name": "honkit-seed",
  "version": "1.0.0",
  "repository": "git@github.com:taretmch/mdoc-honkit-seed.git",
  "author": "taretmch <your-mail@example.com>",
  "license": "MIT",
  "devDependencies": {
    "honkit": "^3.6.17"
  }
}

これで honkit のインストールは完了しました。

Honkit の設定

次に、Honkit の設定を書いていきます。Honkit の設定ファイルは GitBook と同様 book.json です。静的サイトの生成に使用する Markdown ファイルのパス（今回は ./docs/mdoc です。mdoc の出力先のディレクトリを指定しましょう）を指定し、mdoc ビルド後のファイルから静的サイトを生成するようにします。

book.json

{
  "root": "./docs/mdoc/",
  "title": "mdoc と Honkit で Scala ドキュメントを GitHub Pages に公開する",
  "author": "taretmch",
  "language": "ja"
}

Honkit には README.md と SUMMARY.md というファイルが必要なので、honkit init により生成します。

% npx honkit init
warn: no summary file in this book
info: create SUMMARY.md
info: initialization is finished

静的ファイルの生成は、 honkit serve か honkit build によって行います。serve は localhost でサイトを公開するので、手元でサイトを見るのに最適です。

% npx honkit serve ./ ./honkit

localhost:4000 にアクセスすると、下記画像のようなサイトが表示されます。

ただ、ディレクトリの指定などが面倒なので yarn start と yarn build でできるようにしちゃいましょう。package.json に以下の設定を追加します。

package.json

  "scripts": {
    "build": "npx honkit build ./ ./honkit",
    "start": "npx honkit serve ./ ./honkit"
  },

これで、mdoc で書いたファイルを Honkit によって静的サイトにすることができました。

GitHub Actions で GitHub Pages に自動デプロイする

では、Honkit で生成した静的サイトを GitHub Pages にデプロイします。

以下のようなファイル .github/workflows/ci.yml を作成します [1, 2, 3, 4]。設定のバリエーションについては参考リンク先をご覧ください。

.github/workflows/ci.yml

name: CI

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
    - name: Checkout
      uses: actions/checkout@v2

    - name: Setup Scala
      uses: olafurpg/setup-scala@v10
      with:
        java-version: "adopt@1.8"

    - name: Setup Node
      uses: actions/setup-node@v2
      with:
        node-version: '12.x'
    - name: Install dependencies
      run: yarn --frozen-lockfile

    - name: Build Mdoc
      run: sbt docs/mdoc
    - name: Build Honkit
      run: yarn build

    - name: Push to gh-pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_branch: gh-pages
        publish_dir: honkit/

やっていることは以下の通りです。

master ブランチにプッシュされたときに実行されることを宣言する
ubuntu 上で、Scala と NodeJS をインストールする (Setup Scala, Setup Node)
NodeJS の依存パッケージをインストールする (Install dependencies)
mdoc を実行して Markdown ファイルを生成する (Build Mdoc)
Honkit を実行して静的サイトを生成する (Build Honkit)
gh-pages ブランチに honkit/ ディレクトリ下をプッシュする (Push to gh-pages)

このファイルをコミットして master ブランチに上げると、うまく GitHub Actions が走りました！

gh-pages ブランチを確認してみると、Honkit で生成したファイルが作られていることがわかります。

GitHub Pages の設定

最後に、GitHub リポジトリの Settings で gh-pages ブランチを GitHub Pages に公開する設定をすれば完了です。

しばし待つと、、、サイトが公開されました！

下記リンクでアクセスできます。

おわりに

mdoc を使って書いた Scala プロジェクトのドキュメントを、Honkit によって静的サイトにし、GitHub Pages に公開しました。GitHub Actions で GitHub Pages に自動デプロイする設定を追加し、master ブランチにプッシュすれば GitHub Pages が自動で更新されるようになりました。

Scala のプロジェクトでドキュメントを作成・公開したいという方のご参考になればいいなと思い、本記事を執筆しました。よければ OSS のドキュメントを書いて、GitHub Pages に公開してみてください！

GitHub Actions の高速化や Honkit の各種設定についてここで述べられなかったので、別の機会にまとめていければと思います。
最後までお読みいただき、ありがとうございました。

参考リンク

[1] sbt Reference Manual - Setting up GitHub Actions with sbt, https://www.scala-sbt.org/1.x/docs/GitHub-Actions-with-sbt.html, 2021年3月24日閲覧.
[2] scala-text/scala_text, https://github.com/scala-text/scala_text, 2021年3月24日閲覧.
[3] GitHub Actions による GitHub Pages への自動デプロイ, https://qiita.com/peaceiris/items/d401f2e5724fdcb0759d, 2021年3月24日閲覧.
[4] Node.js のビルドとテスト, https://docs.github.com/ja/actions/guides/building-and-testing-nodejs, 2021年3月24日閲覧.