概要
今回はRead the DocsというSphinxのホスティングサービスを利用し、
簡単に美しいWebドキュメントを作成します。
ドキュメント作成はmarkdown、reStructuredTextの両方に対応させます。
前回の記事にてGitリポジトリを起点にAzure Web Appsにコンテンツを配布してくれるようになりました。
(GithubからAzure App Serviceへ継続的デプロイしてみる https://tech-lab.sios.jp/archives/1398)
これにあわせ、マニュアルやドキュメントを同じプロジェクトフォルダ(Gitリポジトリ)
で管理し、Read the Docs でWeb ドキュメントを自動作成してもらいます。
構成
構成は以下の具合です。
コンテンツの更新も、ドキュメントの更新も全てGitリポジトリを起点にします。
それでは、早速Webドキュメントを作成します。
前提して下記の状態であることとします。私はWindows8.1の環境で実施しました。
– Sphinxインストール済み
– Gitインストール済み
– プロジェクトのリポジトリをgit clone済み
ローカルリポジトリにSphinxドキュメントを追加する
プロジェクトフォルダへ移動します。
docs というフォルダを作成し、その中で sphinx-quickstart を実行 します。
C:\repo\dummy> mkdir docs
C:\repo\dummy> cd docs
C:\repo\dummy\docs> sphinx-quickstart
これでSphinxとして必要な最低限のファイルは揃いました。
markdown に対応させる
まずデフォルトでは rstという拡張子(reStructuredText)のみ対応しています。
reStructuredTextとはマークアップ言語でmarkdownと同じでtxtでスラスラ記述でき、markdownよりできることも豊富ですが必要以上にドキュメント作成をがんばる必要がなければmarkdownで記載したいのでこちらにも対応させます。
conf.pyを以下のように修正するだけです。ついでにテーマも巷でよくみるアレに変更します。
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']
html_theme = 'sphinx_rtd_theme'
これをGitリポジトリにcommit,pushすることでRead the DocsがShpinxドキュメントとして自動でビルドしてくれる準備が整います。
ちなみに、ずらずらSphinxとしてのファイルが生成されますがcommitする必要があるのは docsフォルダ内の index.rst と conf.py の2つだけです。
極端な話ローカルでビルドする必要がなかったりローカルにSphinxをインストールするのが億劫な場合はこの2つのファイル(docsフォルダ合わせて3つ)を用意してcommitすれば sphinx-quickstart を実行する必要すらありません。
Read the Docsプロジェクトを作成する
次はRead the Docsにプロジェクトを作成し、Gitリポジトリをインポートします。
Githubアカウントのリポジトリが表示されますが、GithubのOrgnizationsアカウントには対応していませんので、マニュアルでインポートします。
次にインポートするGitプロジェクトを選択し、次に進みます。
Nameはグローバル環境においてユニークである必要があります。
では、早速ビルドと行きたいところですが、下記のようにエラーがでます。
これは、Gitリポジトリ側にWebhookの設定をしてあげる必要があり、この設定をすることで
Read the DocsがGitリポジトリが更新かかったそばから自動でビルドしてくれるようになります。
GithubからWebhookの設定をします。
– Setting
– Webhook
– Payload URL に https://readthedocs.org/build/(read the docs プロジェクト名)をいれます。
– Activeにチェック
※ どうやら、Github Orgnizationsアカウントに対応していないようで、
予めGithubの個人アカウントをJOINしていると自動でWebhookの設定をしてくれます。
では、Read the Docsのページにもどり Build ボタンを実行します。
ビルド完了後、URLにアクセスしてみます。
できたドキュメントはこちら。
ドキュメントの修正はSphinxのソレに則っとる形です。
– index.rst を変種し、構成をつくる
– index.rstに追加した構成のファイルを作成する
以下にサンプルページを公開します。
興味があるかたはpullrequestを頂ければじゃんじゃんマージいたします。
https://siosdummy.readthedocs.io/en/latest/intro.html
まとめ
いかがでしたでしょうか。開発におけるドキュメントの作成は億劫になりがちです。前回、と今回でGitリポジトリを起点にコンテンツはAzure Web Apps、ドキュメントはRead the docsでオートビルド。
リリースにおける作業はマスターリポジトリへマージするだけになりました。是非活用してみて下さい。
