★★★ お知らせ ★★★

◆ 6月のPS Liveは決済サービスStripeのデモ！◆
決済サービスのStripeでサブスクリプションの支払い機能を作ってみた
Stripeの機能の一部を切り出して、簡単なサブスクリプションを作るとどうなるのかを、デモをまじえてご紹介します。
⇒ 詳細はこちらから

◆【セミナー開催】可視化ツールGrafana～初めてのダッシュボード作成◆
デモンストレーション付き！
本セミナーでは、売上データを用いて、4種類のパネル作成方法をお見せします。
⇒ お申込みはこちらから

◆ エンジニア業務環境アンケート結果 ◆
エンジニアが自分の働き方にどういったことで満足していて、不満を感じているのか、働きたい会社像として何を求めているのか、業務環境調査を実施しました。ぜひご覧ください。
⇒ アンケート結果はこちらから

1 概要

概要

今回は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でオートビルド。
リリースにおける作業はマスターリポジトリへマージするだけになりました。是非活用してみて下さい。