DiaryException このページをアンテナに追加 RSSフィード

2010-11-06(土)

[][]Paver/SphinxOMakeドキュメント生成/公開を自動化する

前提と目標

ドキュメントはreStructuredText(reST)で書き、htmlドキュメントに変換される(ドキュメント生成)。生成されたhtmlドキュメントリモートサーバにscpで転送され、公開される(ドキュメント公開)。

ドキュメントを書くことのみに集中し、ドキュメント生成と公開は自動化したい。

用いるツール

ドキュメント生成/公開手順

まず、プロジェクトHOGEディレクトリを作る。

f:id:LaclefYoshi:20101106184110p:image

次に、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"),
# ...

f:id:LaclefYoshi:20101106191510p:image

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

f:id:LaclefYoshi:20101106191511p:image

OMakefileを編集する。

.PHONY: publish

publish: $(glob docs/source/*)
    paver publish
$ pwd
HOGE
$ omake -P --verbose publish
# ターゲットはpublish
# ファイル監視/自動ビルドのため待機(終了するにはC-c)

これで、docs/source/以下のファイル編集される度に、自動的にビルドコマンド:paver publishが実行される、つまりhtmlドキュメントの生成とリモートサーバへのドキュメントファイル転送が行われる。

まとめ

これまで

emacs上でreSTドキュメントを書く -> 端末(emacsシェル)に移動しpaver publish -> emacsに戻りドキュメント編集する -> 端末に移動しpaver publish -> ...

これから

emacs上でreSTドキュメントを書く -> emacs上ででドキュメント編集する -> ...
(裏では、ドキュメント編集される度にOMakeがpaver publishしている)
2005 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |
2006 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |
2007 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |
2008 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |
2009 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |
2010 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |
2011 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |
2012 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |
2013 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |
2014 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |
2015 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |
2016 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |
2017 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 |