ドキュメントのホスティングサービスRead the DocsにはGitHubと連携する機能があり、
作成したドキュメントをGitHubに登録しておくと、Read the Docsのサーバで自動でビルドしてインターネット上に公開することが出来る。一度連携の設定をしておくと、あとはMarkdownのソースをGitHubのリポジトリに投げるだけで勝手にドキュメントの公開までやってくれるようになるので非常に便利。
Read the Docsはマークアップ言語にrestructuredtextを用いドキュメント生成エンジンにSphinxを使うのがデフォルトだが、 ドキュメント生成エンジンにMkDocsを選択すればマークアップ言語にMarkdownを使うことも出来る。
今回は、MkDocsで作った文書をRead the Docsで自動公開するための設定をひととおりやってみた。
GitHubリポジトリの準備
GitHubリポジトリを作成する。リポジトリの作成方法については、以下の過去記事を参照。
Read the DocsのフリーアカウントでGitHubと連携させるためには、リポジトリ設定をprivateではなくpublicにしておく必要があるので注意。リポジトリの新規作成時にprivate/publicの選択をpublicに指定すればOK。あるいは、作ったprivateリポジトリを以下の手順でpublicに変更する。
- GitHubにログインし、右上のドロップダウンメニューから”Your repositories”を選択
- リポジトリの一覧から”test”リポジトリを選択する
- testリポジトリの右上にある歯車マーク”Settings”タブを開く
- ページの一番下の方にある赤枠”Danger Zone”の中にある”Make public”ボタンを押す
設定したリポジトリをローカルにcloneする。
$ git clone https://github.com/goediy/test
$ cd test
MkDocsドキュメントをGitHubリポジトリに追加する
MkDocsドキュメントは、過去記事で作成した物を流用する。
MkDocsでRead the Docs用ドキュメントを作る
この時作ったファイルの構成はこんな。
|- mkdocs.yml
|
|- docs/
|- index.html
|- test.md
これらをローカルリポジトリのディレクトリにコピーした後、以下のコマンドでリポジトリに追加する。
$ git add -A
コミットして追加を確定。
$ git commit -m "added MkDocs Documents"
サーバへ反映させる
$ git push origin master
Read the Docs設定ファイルの準備
Read the DocsとGitHubを連携させるためには、プロジェクトのルートディレクトリにRead the Docs用の設定ファイルを置いておく必要がある。詳細は、Read the Docsの本家ドキュメントに説明がある。
設定ファイルはreadthedocs.ymlなど指定のファイル名(他の選択肢はreadthedocs.yaml,readthedocs.yaml,readthedocs.yamlのいずれか)にする必要がある。GitHubローカルリポジトリ上にreadthedocs.ymlを以下の内容で作成。
version: 2
mkdocs:
configuration: mkdocs.yml
fail_on_warning: false
formats: all
python:
version: 3.6
install:
- requirements: docs/requirements.txt
上記、readthedocs.ymlの3行目以降はmkDocsに関するセクションで、
4行目でリポジトリに追加済みのmkDocsの設定ファイルmkdocs.ymlを指定している。
9行目以降はRead the Docsのサーバ上で動作するPythonがドキュメントのビルドを行うために必要な設定を行っている。
10行目にPythonのバージョンを指定しているが、ローカルでMkDocsのテストを行ったバージョンと同じにしておいた方が良いだろう。
11行目は必要なパッケージを列挙したテキストファイルをdocs/requirements.txtと指定している。これは実際にリポジトリに配置する必要があるファイルで、中身はドキュメントのビルドに必要なPyPIパッケージ名を列挙する。例えば以下のような感じ。
pymdown-extensions==7.0
mkdocs-material==5.0.2
前掲の過去記事「MkDocsでRead the Docs用ドキュメントを作る」にてpipでインストールしたパッケージ名を列挙している(Materialテーマを使うためのmkdocs-materialパッケージと、数式を使うためのpymdown-extensions)。==の後ろはバージョン番号で、これもローカルと同じにしておくのが無難だろう。
上記の追加ファイルをリポジトリに配置し、コミット&サーバにpushしておく。
$ git add readthedocs.yml docs/requirements.txt
$ git commit -m "added readthedocs.yml"
$ git push origin master
GitHubとRead the Docsを連携させる
以下の手順を実行。
- Read the Docsアカウントを作っていない場合は、まずアカウントを作成する
- Read the Docsにログインし画面右上の自分のアカウント名の所をクリックするとドロップダウンが開くので、「設定」をクリック
- 管理画面が開くので、左側から「接続したサービス」タブをクリックする
- 「接続したサービス」タブの下の方にある”Connect to GitHub”ボタンを押す
- Read the Docsと連携して良いかどうかを確認する”Authorize Read the Docs Community”というタイトルのgithubのページが表示されるので、緑の”Authorize readthedocs”ボタンを押して連携を完了する(GitHubのパスワードを聞かれる)
- Read the Docsの管理画面に戻ると「接続したサービス」タブの中に連携したGitHubアカウントが表示されている
GitHubからRead the Docsへドキュメントをインポートする
連携が終わったら、いよいよGitHubからドキュメントのインポートを行う。
- 画面右上の自分のアカウント名の所をクリックしてドロップダウンから「自分のプロジェクト」を選択
- Read the Docsのダッシュボードが開くので、「プロジェクトを取り込む」と書かれたボタンを押す
- 「リポジトリをimport」と書かれたページが開く。”No remote repositories found, try refreshing your accounts.”というメッセージの中のリンクが見える場合は、クリックしてリフレッシュする
- 下のキャプチャのように、箱の中にGitHubのリポジトリが見えるようになるのでボックスの中の”+”をクリックする
- プロジェクト詳細画面でプロジェクトの「名前」を指定する。この名前はRead the Docs全体でユニークな物にする必要がある。デフォルトの”test”だと重複するとエラーが出て弾かれるので、”goediy_test”など適宜変更。
- 「次へ」ボタンを押すと設定が完了し、プロジェクトのページが自動生成される。
プロジェクトのページで「ビルドバージョン」を押すと、ドキュメントのRead the Docsのサーバ側でビルドが開始され、暫く待っていると公開される。生成されたページは以下(クリックすると実際のページが表示出来ます)。
materialテーマも数式も問題なく表示出来ている。
まとめ
MkDocsで作成したドキュメントをGitHubに登録して、Read the Docsと連携する一連の作業を行った。Read the Docsサーバ上で動作するPythonの設定に関しては、公式ドキュメントにもちゃんとした記述が無く少々ハマった。が、無事Read the Docsサーバ上でもテーマを変えたり数式を記述したり可能と確認出来た。
ローカルリポジトリでドキュメントのMarkdownソースを編集し、GitHubサーバにpushしてみたところ、Read the Docsサーバにも通知されて自動でビルドもされる事も確認出来た。一度設定してしまえば、あとはドキュメントの内容を書くことに集中できるので、インターネットに公開するドキュメントを作る際は非常に便利な仕組みだと思う。
今回設定したGitHubのリポジトリとRead the Docsのドキュメントはそのままにしておくので、ご参考にどうぞ。
コメント