Sphinx＋Drone＋S3で快適ドキュメントライフ

ドキュメントの維持管理はどんな組織においても永遠の課題と思います。
今回はサーバープラットフォームチームで取り入れている永続化したい社内向けドキュメントの維持管理の仕組みをご紹介します。

Sphinx とは

Sphinx は Python ベースのドキュメント生成ツールです。
マークアップ言語である reStructuredText をソースとして、 HTML で構成されたドキュメントをビルドできます。
プラグインを入れれば Markdown や AsciiDoc をソースにすることもできますし、 PlantUML を埋め込んだりすることもできます。

Sphinx ドキュメントのホスティング

Sphinx で作ったドキュメントを公開したいのであれば readthedocs.org を使うのが簡単です。
Github や Gitlab を利用しているなら github.io や Gitlab Pages を使うのも良いでしょう。
当社では AWS を活用しており、 Sphinx で生成されたファイルを S3 に置いて適当なドメインにホスティング、公開範囲を適当なポリシーで制限する、というようなことをやっています。

Drone とは

Drone は Go ベースの CI ツールです。
Git リポジトリへのイベントを契機に、 Docker コンテナ内でジョブを実行するというシンプルなツールです。
当社では開発用に社内に Drone サーバを構築して運用しています。

概要

以下のようなフローで Gitlab への push を契機に、 Drone で Sphinx ドキュメントをビルドし、 S3 へアップロードします。

これによって

• ドキュメントを書く人はマークアップ言語で記述できる
• ドキュメントを読みたい人は HTML で構造化された形式で読める
• ドキュメントが更新されたタイミングは Slack 通知で検知可能
• Git 管理されてるので diff や log も当然見れる

を実現しています。

やること

AWS

1. アップロード用の S3 バケットを用意
2. S3 バケットの AWS アクセスキーと AWS アクセスシークレットを取得
3. S3 バケットを適当なドメインにホスティング

Drone

1. Gitlab との連携を ON にする
2. S3 の AWS アクセスキーと AWS アクセスシークレットを登録する

Gitlab

1. Drone url と Token を設定する

2. Sphinx ドキュメント用のレポジトリで .drone.yml を以下の様に書く（ S3 アップロード用の docker イメージには atlassian/pipelines-awscli を利用）

   pipeline:
     build:
       image: python:3
       commands:
         - pip install Sphinx
         - make html
       when:
         event: push
         branch: master
   
   push-contents:
       image: atlassian/pipelines-awscli
       secrets:
         - AWS_ACCESS_KEY_ID
         - AWS_SECRET_ACCESS_KEY
       commands:
         - aws s3 sync --delete _build/html/ s3://<作成した S3 バケット名>/
       when:
         event: push
         branch: master
   

3. 以上で master に push されたタイミングで Sphinx ドキュメントが出来上がるようになります

さいごに

ドキュメント作成はしばしば気が重くなる作業ですが、避けては通れないものでもあります。
しかし綺麗なドキュメントが楽に書ける仕組みがあると、不思議と筆は進んでいくものです。
皆さんもサーバーサイドアプリケーションエンジニアとして、当社で快適なドキュメントライフを送りませんか？
https://jobs.qiita.com/postings/238