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

★★★ お知らせ ★★★

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

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

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

概要

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

アバター画像
About サイオステクノロジーの中の人 41 Articles
サイオステクノロジーで働く中の人です。
ご覧いただきありがとうございます! この投稿はお役に立ちましたか?

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

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


ご覧いただきありがとうございます。
ブログの最新情報はSNSでも発信しております。
ぜひTwitterのフォロー&Facebookページにいいねをお願い致します!



>> 雑誌等の執筆依頼を受付しております。
   ご希望の方はお気軽にお問い合わせください!

Be the first to comment

Leave a Reply

Your email address will not be published.


*


質問はこちら 閉じる