12
8

More than 3 years have passed since last update.

PkgTemplates による Julia パッケージの作り方(後半)

Last updated at Posted at 2019-05-26

本日は

Juliaの Documenter によるドキュメント生成を PkgTemplates から自動生成しドキュメントをGitHubPagesから閲覧できるようにする(前半) の続きです。

ローカルの環境で Documenter.jl によるドキュメントをソースコードの docstring をベースに生成することができました。今回はGitHubPagesにてそのドキュメントを公開する方法を紹介します。Travis CIと連携することでソースコードをプッシュして master ブランチにマージすることでドキュメントを更新自動で行うことができます。master にマージされないとドキュメントの自動更新はされないようです。

デプロイキーを作ります。

概要

Documenter.jl のドキュメント を読むとSSH Deploy Keys が必要になるようです。Overview にもあるように Travis CI は HTML に変換されたドキュメントを対象のリポジトリの gh-pages ブランチにプッシュしますので、GitHubリポジトリの操作を許可するためにもちいられるんだとおもいます。

DocumenterTools による鍵生成

DocumenterTools パッケージを導入します。

pkg> add DocumenterTools

つぎの手順でドキュメントを公開するみなさんのGitHubのリポジトリ用の鍵をつくります。

julia> using DocumenterTools
julia> Travis.genkeys(user="GitHubユーザ名", repo="git@github.com:GitHubユーザ名/リポジトリ名.git")
[ Info: add the public key below to ...
# リポジトリに配置する公開鍵
[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to ...
# Travis CI の環境変数に追加するための値

短めの文字列と、長めの文字列2種類生成されたと思います。前者がGitHubのリポジトリに設定するもの、後者はTravis CIに追加するものです。

GitHubリポジトリにDeployキーを追加

みなさんのリポジトリにの画面上にある Settings に移動します。

image.png

画面左側にある Deploy keys に移動。

image.png

そして右上にある Add deploy key を押します。

image.png

そうするとTitleとKeyという項目が出てきてきます。ここではTitleをTravisDocumenter
としておきます。各自わかりやすい名前にしておけば問題ないでしょう。Key は先ほど生成した短い文字列をそっくりそのままコピーします。

最後に Allow write access にチェックを追加し保存します。

Travis CI 側に環境変数を追加

ながーい方の文字列をTravis CIの環境変数に追加します。

  • GitHub のアカウントを用いて Travis CI のアカウントを作ります。
  • Travis CI とリポジトリを連携

が必要です。ここでは手順を省略します。下記のように対象となるリポジトリがつかされていることを確認します。(画像では HelloWorld.jl です.)

画面右側にある Settings ボタンを押します。

image.png

Settings ページの真ん中辺りに Environment Variables があるので DOCUMENTER_KEY を左のテキストに、上で生成した長い文字列を右側に入力します。

image.png

そして Add ボタンを押して完了です。Display value in build log は触らないこと!

この後は画面上にある Dashboard の画面に移動しビルドをさせます。

image.png

上の画面にある HelloWorld.jl をクリックして移動します。
そうすると下記のような画面が出てきます。

image.png

# 1.5 を押すと Job log でなんかいろんなことやってそうだなーという雰囲気がつかめると思います。

Done. Your build exited with 0. の出力が出れば一安心です。

出力の確認

リポジトリに戻ってREADMEに表示されるバッジを確認します。 buld passing が灰色から緑色になっていることがわかりますね。(ここではそもそもテスト書いてないのでただ通るだけなんですが・・・)

image.png

docs dev ボタンを押すと下記のようにページが表示されていることがわかります。

image.png

docs stable も閲覧可能にする。

stable のほうのドキュメントが反映されていないのはバージョンの tag をつけていないからです。
ここでは練習目的で GitHub の Release 機能を用いた v0.1.0 というタグをつけておきましょう。

リポジトリにもどって releases に移動します。
image.png

create new release ボタンを押して 

image.png

image.png

そんでもって Publish release を押します。そうすると自動的に Travis CI が自動で動きます。
しばらくまつとCIのテスト・ドキュメント生成が終わりますので docs stable をクリックすると反映されますね。

以上で自動的に Documenter.jl, Travis CI によって Juliaパッケージのドキュメントを生成することができました。各自 docstring を充実して使いやすいパッケージを目指していきましょう。

12
8
1

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
12
8