MyEnigma

とあるエンジニアのブログです。#Robotics #Programing #C++ #Python #MATLAB #Vim #Mathematics #Book #Movie #Traveling #Mac #iPhone

GitHubのOSSで最新のドキュメントを各コミット毎に簡単に確認できるようにする


SphinxでKindle本を作る

目次

はじめに

OSSにとってドキュメントは、

出来るだけ多くの人に使ってもらうために重要です。

 

近年のOSSでは、

ソースコードと同じgitリポジトリに

テキストベースでドキュメントの元のデータを管理し、

Sphinxや

www.sphinx-doc.org

Documenter,jl

github.com

のようなドキュメント作成ライブラリを使って、

htmlベースのドキュメントを自動生成し、

そのデータをインターネット上に公開するのが一般的です。

 

このようにドキュメントをgitで管理すると、

ドキュメントの改善を通常のコードと同様に

プルリクエストベース(PR)で、レビューして

改善することができます。

 

このような、

PRベースでドキュメントの変更をレビューするのは便利なのですが、

一つ面倒なのが、

他人のドキュメントのPRをレビューするときに、

そのPRのブランチを手元にチェックアウトし、

ドキュメントをビルドしないと、

最新のドキュメントの見た目などを確認できないことです。

 

また、レビューの結果を反映した、

各コミット毎にこの作業をしないといけないので

以前から非常に面倒だなと感じていました。

 

昔からこのフローを改善したいなと思っていたのですが、

最近開発に参加している、SciPyが非常に良い方法を利用しているのに気がつきました。

github.com

 

この方法では、

PRの各コミット毎にCIが回るので、

そのCIの一環として、最新のコードでドキュメントをビルドし、

そのドキュメントをそのままブラウザ上で確認出来るようになります。

 

もう少し具体的には、

下記のように、PRでコミットすると

GitHubのCIの画面に、

build_doc artifactという項目が表示され、

f:id:meison_amsl:20200725204409p:plain

 

この項目のDetailsをクリックすると、

下記のように、CIで生成された最新のドキュメントを

ブラウザ上で確認することができます。

f:id:meison_amsl:20200725204515p:plain

これを見ながら、

簡単に最新のドキュメントの結果をレビューすることができます。

 

今回の記事では、

こちらの設定方法について説明します。

Circle CIでドキュメントをビルドするCIを作る

現時点では、CIで作成したドキュメントのファイルに、

ブラウザから直接アクセスして閲覧できるのは、

Circle CIしかありません。

circleci.com

(GitHub actionsでも対応を要望するissueが作成されていますが、

まだ対応されていません。

github.com)

 

したがって、

Circle CIのCIでドキュメントをビルドして、

作成されたartifactを保存する必要があります。

具体的には、ドキュメントビルダーをしてSphinxを使っている場合は、

github.com

Documenter.jlを使っている場合は、

github.com

を参考にCircleCIの設定してもらえると良いと思います。

大事なのは、ドキュメントを生成したあと、

そのドキュメントをstore_artifactsすることです。

 

ここまで設定できると、CIが成功したあとに、

CircleCIのページから、

生成されたドキュメントにブラウザからアクセスできるようになります。

 

しかし、この生成されたドキュメントへのアクセスは、

毎回、circle ciのページに移動し、そこからリンクを辿る必要があるので、

すこし面倒です。

 

circleci-artifacts-redirectorを設定する

続いて、先程のドキュメントへのアクセスをできるだけ簡単にするために、

下記のgithub actionを設定します。

github.com

このgithub actionsは、先程のCircle CIのドキュメントへのリンクを

自動的に抽出し、そのリンクを先程の画像のように、

CIの一つのDetailsからアクセスできるようにするものです。

 

具体的なGitHub actionsの設定は

下記の設定を参考に設定できると思います。

github.com

artifact-pathの0/の後ろのパスを、

先程のCircleCIで生成したドキュメントへのパスにする必要があります。

 

ちなみに、この上記のGitHub actionsのREADMEでは、

Example Usageのyamlファイルで、

最後にcurlでURLを確認していますが、

自分の環境では、たまにそのstepが失敗することがあり、

毎回、通知が来てしまって、ウザかったので削除しました。

今の所、それでも問題なく動いています。

 

参考資料

myenigma.hatenablog.com

myenigma.hatenablog.com

myenigma.hatenablog.com

myenigma.hatenablog.com

myenigma.hatenablog.com

myenigma.hatenablog.com

 

MyEnigma Supporters

もしこの記事が参考になり、

ブログをサポートしたいと思われた方は、

こちらからよろしくお願いします。

myenigma.hatenablog.com