Scala のプロジェクトのドキュメントを mdoc で書いて、Honkit と GitHub Pages でドキュメントを公開し、GitHub Actions でデプロイを自動化する、までをやってみました。
- サンプルコード
- プロジェクトの作成
- mdoc で Scala プロジェクトのドキュメントを書く
- Honkit で Markdown ファイルから静的サイトを生成する
- GitHub Actions で GitHub Pages に自動デプロイする
- GitHub Pages の設定
- おわりに
- 参考リンク
サンプルコード
本記事で作成したサンプルコードです。
サンプルコードは下記の 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
に設定を追加すれば完了です。
addSbtPlugin("org.scalameta" % "sbt-mdoc" % "2.2.18" )
本サンプルプロジェクトでは、 docs
ディレクトリを一つのプロジェクトとし、 docs/src/main
にドキュメントを作っていくことにします。docs
プロジェクトに MdocPlugin
を有効化して、作業ディレクトリ (mdocIn
) に docs/src/main
を指定し、コンパイル後のファイル (mdocOut
) を docs/mdoc
に置くよう指定しています。
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
が以下のようになっているかと思います。
{ "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 ビルド後のファイルから静的サイトを生成するようにします。
{ "root": "./docs/mdoc/", "title": "mdoc と Honkit で Scala ドキュメントを GitHub Pages に公開する", "author": "taretmch", "language": "ja" }
Honkit には README.md
と SUMMARY.md
というファイルが必要なので、生成します。
% 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
に以下の設定を追加します。
"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]。設定のバリエーションについては参考リンク先をご覧ください。
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日閲覧.