◆ Live配信スケジュール ◆
サイオステクノロジーでは、Microsoft MVPの武井による「わかりみの深いシリーズ」など、定期的なLive配信を行っています。
⇒ 詳細スケジュールはこちらから
⇒ 見逃してしまった方はYoutubeチャンネルをご覧ください

【5/21開催】Azure OpenAI ServiceによるRAG実装ガイドを公開しました
生成AIを活用したユースケースで最も一番熱いと言われているRAGの実装ガイドを公開しました。そのガイドの紹介をおこなうイベントです!!
https://tech-lab.connpass.com/event/315703/

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