Paver/SphinxとOMakeでドキュメント生成/公開を自動化する
前提と目標
ドキュメントはreStructuredText(reST)で書き、htmlドキュメントに変換される(ドキュメント生成)。生成されたhtmlドキュメントはリモートサーバにscpで転送され、公開される(ドキュメント公開)。
ドキュメントを書くことのみに集中し、ドキュメント生成と公開は自動化したい。
用いるツール
- http://www.blueskyonmars.com/projects/paver/
- プロジェクトに関わる雑多なタスクを定義して、簡単に実行出来るようにするツール
- Overview — Sphinx 2.1.0+/12c614911 documentation
- 発表資料 — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
- The OMake build system
- 1. ガイド — OMakeマニュアル 日本語訳
- Makeより高機能なビルドツール
ドキュメント生成/公開手順
まず、プロジェクトHOGEのディレクトリを作る。
次に、Sphinx用ドキュメントディレクトリを作る。セットアップ支援があるので利用する。
$ pwd HOGE $ sphinx-quickstart # セットアップ支援 / 色々聞かれるので適当に答える # ドキュメントルートディレクトリ名: docs # ドキュメントソースディレクトリ名: source # ドキュメントビルドディレクトリ名: build
Paverを使って、ドキュメントを生成するために、pavement.pyを作る。
from paver.easy import * from paver.setuputils import setup import paver.doctools options( setup( # ... sphinx = Bunch( docroot = "docs", builddir = "build", sourcedir = "source"), # ...
docs/source/index.rstを適当にいじったり、同じディレクトリに別ファイル.rstを作ったりしてドキュメントを書く。詳しくは、Sphinxの説明書を参照すること。
ドキュメントソースを書いたら、htmlドキュメントを生成する。
$ pwd HOGE $ paver html # docs/source/以下のrstファイルを元に、docs/build/html/以下にhtmlドキュメントが生成される
生成されたhtmlドキュメントをリモートサーバで公開するタスクを、pavement.pyに以下のように書いて定義する。
@task @needs('paver.doctools.html') def publish(): src = "docs/build/html/*" dst = "saeki@example.org:./public_html/hoge" sh("scp -r %s %s" % (src, dst))
$ paver publish
# docs/build/html/以下のhtmlドキュメントを(無ければ paver htmlで生成して)、リモートサーバにscpで転送する
ドキュメント生成/公開の自動化
docs/source/以下のファイルをいじる度に、端末(もしくはemacsのシェル)でpaver publishを実行するのは面倒。
そこで、OMakeのファイル監視/自動ビルド機能を活用する。
$ pwd HOGE $ omake --install # 全てのサブディレクトリにOMakefileを配置するなら--install-all
OMakefileを編集する。
.PHONY: publish publish: $(glob docs/source/*) paver publish
$ pwd HOGE $ omake -P --verbose publish # ターゲットはpublish # ファイル監視/自動ビルドのため待機(終了するにはC-c)
これで、docs/source/以下のファイルが編集される度に、自動的にビルドコマンド:paver publishが実行される、つまりhtmlドキュメントの生成とリモートサーバへのドキュメントファイル転送が行われる。
