目次
はじめに
OSSにとってドキュメントは、
出来るだけ多くの人に使ってもらうために重要です。
近年のOSSでは、
ソースコードと同じgitリポジトリに
テキストベースでドキュメントの元のデータを管理し、
Sphinxや
Documenter,jl
のようなドキュメント作成ライブラリを使って、
htmlベースのドキュメントを自動生成し、
そのデータをインターネット上に公開するのが一般的です。
このようにドキュメントをgitで管理すると、
ドキュメントの改善を通常のコードと同様に
プルリクエストベース(PR)で、レビューして
改善することができます。
このような、
PRベースでドキュメントの変更をレビューするのは便利なのですが、
一つ面倒なのが、
他人のドキュメントのPRをレビューするときに、
そのPRのブランチを手元にチェックアウトし、
ドキュメントをビルドしないと、
最新のドキュメントの見た目などを確認できないことです。
また、レビューの結果を反映した、
各コミット毎にこの作業をしないといけないので
以前から非常に面倒だなと感じていました。
昔からこのフローを改善したいなと思っていたのですが、
最近開発に参加している、SciPyが非常に良い方法を利用しているのに気がつきました。
この方法では、
PRの各コミット毎にCIが回るので、
そのCIの一環として、最新のコードでドキュメントをビルドし、
そのドキュメントをそのままブラウザ上で確認出来るようになります。
もう少し具体的には、
下記のように、PRでコミットすると
GitHubのCIの画面に、
build_doc artifactという項目が表示され、
この項目のDetailsをクリックすると、
下記のように、CIで生成された最新のドキュメントを
ブラウザ上で確認することができます。
これを見ながら、
簡単に最新のドキュメントの結果をレビューすることができます。
今回の記事では、
こちらの設定方法について説明します。
Circle CIでドキュメントをビルドするCIを作る
現時点では、CIで作成したドキュメントのファイルに、
ブラウザから直接アクセスして閲覧できるのは、
Circle CIしかありません。
(GitHub actionsでも対応を要望するissueが作成されていますが、
まだ対応されていません。
したがって、
Circle CIのCIでドキュメントをビルドして、
作成されたartifactを保存する必要があります。
具体的には、ドキュメントビルダーをしてSphinxを使っている場合は、
Documenter.jlを使っている場合は、
を参考にCircleCIの設定してもらえると良いと思います。
大事なのは、ドキュメントを生成したあと、
そのドキュメントをstore_artifactsすることです。
ここまで設定できると、CIが成功したあとに、
CircleCIのページから、
生成されたドキュメントにブラウザからアクセスできるようになります。
しかし、この生成されたドキュメントへのアクセスは、
毎回、circle ciのページに移動し、そこからリンクを辿る必要があるので、
すこし面倒です。
circleci-artifacts-redirectorを設定する
続いて、先程のドキュメントへのアクセスをできるだけ簡単にするために、
下記のgithub actionを設定します。
このgithub actionsは、先程のCircle CIのドキュメントへのリンクを
自動的に抽出し、そのリンクを先程の画像のように、
CIの一つのDetailsからアクセスできるようにするものです。
具体的なGitHub actionsの設定は
下記の設定を参考に設定できると思います。
artifact-pathの0/の後ろのパスを、
先程のCircleCIで生成したドキュメントへのパスにする必要があります。
ちなみに、この上記のGitHub actionsのREADMEでは、
Example Usageのyamlファイルで、
最後にcurlでURLを確認していますが、
自分の環境では、たまにそのstepが失敗することがあり、
毎回、通知が来てしまって、ウザかったので削除しました。
今の所、それでも問題なく動いています。
参考資料
MyEnigma Supporters
もしこの記事が参考になり、
ブログをサポートしたいと思われた方は、
こちらからよろしくお願いします。
