ご安全に!ryosmsです。

Read the Docsでドキュメントを作って独自ドメイン設定するまでの備忘録。

...の前に
Read the Docs #とは
  • SphinxMkDocsで作成されたドキュメントをホストしてくれるサービス
  • 公開されているSphinx(or MkDocs)なリポジトリをビルドして公開してくれる
  • GitHubアカウント、bitbucketアカウントと連携させると自分のリポジトリを読みこんでくれる(※ただしpublicリポジトリのみ)
  • 各言語のリポジトリを指定することで複数言語のドキュメントの公開も可能



Read the Docsでドキュメントを公開する方法は簡単です。

なお、Read the Docsにアカウントがないことには話にならないので登録してる前提です。

1. プロジェクトの作成
Read the Docsにログインして、右上のアカウントメニューより「Add Project」をクリックします。
08

プロジェクトの作成方法には以下の3種類があります。
  1. アカウントをGitHubと連携させてリポジトリから選択する
  2. アカウントをbitbucketと連携させてリポジトリから選択する
  3. プロジェクトに使用するリポジトリのURLを自分で指定する
3のマニュアル指定した場合は自分でプロジェクトの情報を入力する必要があります。
1, 2のアカウント連携を使用した場合は自動で入力されます。
59

Edit advanced project optionsにチェックを入れると次へボタンをクリックした後にプロジェクトの詳細情報を指定することができます。(後からでも変更できるので今回はスルー)

2. プロジェクトのビルド
プロジェクトが作成できたら、自動でClone→インストール→ビルドが走るので、完了するまでしばらく待ちます。

41

htmlのビルドが成功したらドキュメントが公開されています。ドキュメントのURLはhttp://<プロジェクト名>.readthedocs.comです。
これでRead the Docsでドキュメントの公開が完了しました。

3. WebHookの設定
リポジトリにpushしたら自動でビルドが走るように設定します。
GitHubの場合はリポジトリのsettings→Webhooks & ServicesページのAdd serviceでRead the Docsを選択してAdd Serviceするだけです。
bitbucketも同様に、リポジトリのsettings→HooksページのSelect a hookからRead the Docsを選択してAdd hookするだけです。
その他の場合は、プロジェクトページの右下の方にHookのコマンドが書いてあるのでそれを設定すればよさげです。

4. 独自ドメインの設定
Read the Docsのプロジェクトに独自ドメインを設定するのも簡単で、Read the Docsのマニュアルに書いてある通り、CNAMEのポイント先のアドレスに作成したプロジェクトのドキュメント公開URLを設定するだけです。

以上で、Read the Docsでドキュメントを公開できました。