Read the Docsを利用して美しいWebドキュメントを作成する

概要

今回は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リポジトリを起点にします。
screenshot-1473928226

それでは、早速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.rstconf.py の2つだけです。
極端な話ローカルでビルドする必要がなかったりローカルにSphinxをインストールするのが億劫な場合はこの2つのファイル(docsフォルダ合わせて3つ)を用意してcommitすれば sphinx-quickstart を実行する必要すらありません。

Read the Docsプロジェクトを作成する

次はRead the Docsにプロジェクトを作成し、Gitリポジトリをインポートします。
Githubアカウントのリポジトリが表示されますが、GithubのOrgnizationsアカウントには対応していませんので、マニュアルでインポートします。
screenshot-1473908725

次にインポートするGitプロジェクトを選択し、次に進みます。
Nameはグローバル環境においてユニークである必要があります。

screenshot-1473908756

では、早速ビルドと行きたいところですが、下記のようにエラーがでます。
これは、Gitリポジトリ側にWebhookの設定をしてあげる必要があり、この設定をすることで
Read the DocsがGitリポジトリが更新かかったそばから自動でビルドしてくれるようになります。
screenshot-1473923433

GithubからWebhookの設定をします。
– Setting
– Webhook
– Payload URL に https://readthedocs.org/build/(read the docs プロジェクト名)をいれます。
– Activeにチェック
※ どうやら、Github Orgnizationsアカウントに対応していないようで、
予めGithubの個人アカウントをJOINしていると自動でWebhookの設定をしてくれます。
screenshot-1473909496

では、Read the Docsのページにもどり Build ボタンを実行します。
ビルド完了後、URLにアクセスしてみます。
screenshot-1473924091

できたドキュメントはこちら。
screenshot-1473909552

ドキュメントの修正はSphinxのソレに則っとる形です。
– index.rst を変種し、構成をつくる
– index.rstに追加した構成のファイルを作成する

以下にサンプルページを公開します。
興味があるかたはpullrequestを頂ければじゃんじゃんマージいたします。

https://siosdummy.readthedocs.io/en/latest/intro.html

screenshot-1473925824

まとめ

いかがでしたでしょうか。開発におけるドキュメントの作成は億劫になりがちです。前回、と今回でGitリポジトリを起点にコンテンツはAzure Web Apps、ドキュメントはRead the docsでオートビルド。
リリースにおける作業はマスターリポジトリへマージするだけになりました。是非活用してみて下さい。

ご覧いただきありがとうございます! この投稿はお役に立ちましたか?

役に立った 役に立たなかった

1人がこの投稿は役に立ったと言っています。

コメントを残す

メールアドレスが公開されることはありません。 が付いている欄は必須項目です