目次

前のトピックへ

reST と CotEditor

次のトピックへ

日本語検索強化

このページ

Sphinx と git

reST のファイルをgitで管理する

reSTファイルをgit で管理したい場合は、単に sphinx のカレントディレクトリで git init すれば良い

$ git init

sphinxのビルドファイルのバージョンをいちいち管理したくないため、Sphinxの作るシステムディレクトリをまとめて管理から除外する。 ついでに、Mac環境の .DS_Store も除外してしまう。 [1]

$ echo "_*" >> .gitignore
$ echo ".DS_Store" >> .gitignore

また、日本語が通るようにオプションも追加する

$ git config --global core.quotepath false

他に変更がなければ、add と commit してしまう。

$ git add .
$ git commit -m "初めてのコミット"

これで git のレポジトリ管理が始まる。 [2]

サーバーとの同期とか、サーバ上での公開に関する小技

git レポジトリ化したってことは、サーバにUpして分散管理もできる。 今回は手っ取り早くsshサーバによるgitの管理をやってみた。

まずはサーバ側で受入れるためのディレクトリを用意する

$ mkdir -p /path/to/Sphinx.git
$ cd /path/to/Sphinx.git
$ git --bare init

つぎに、ローカルホストにてアップ先を定義して、サーバにUPする。

$ git remote add sicafe.net ssh://username@sicafe.net:22/path/to/Sphinx.git
$ git push sicafe.net master
username@sicafe.net's password:
Counting objects: 9, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (8/8), done.
Writing objects: 100% (9/9), 10.57 KiB, done.
Total 9 (delta 0), reused 0 (delta 0)
To ssh://username@sicafe.net:22/path/to/Sphinx.git
 * [new branch]      master -> master

さて、Upしたサーバでレポジトリの内容を利用したい場合は、git clone すればよい

$ cd /path/to/somedir
$ git clone /path/to/Sphinx.git
Cloning into Sphinx...
done.
$ cd Sphinx
$ ls
Makefile  codeBlockByPygments.rst  conf.py  index.rst  installAndFirstProject.rst  reSTandCotEditor.rst

ここで注意する必要があるのが、 _build ディレクトリについてである。 先ほど .gitignore に _* を追加してしまっているので、ビルドに必要なファイルが 生成されていない状態となっている。 たとえサーバにsphinxがインストールされていても、このまま make html とかしても、ディレクトリが存在しないというエラーが発生してしまう。 そこで、以下のように必要最低限のディレクトリを手動生成してあげる必要がある。

$ mkdir -p ./{_build/doctrees,_build/html,_static,_templates}

これで make html しても問題なく動く。

他のディレクトリに html ファイルを生成させたい場合

たとえばサーバでhtmlを公開したい場合、HTMLファイルだけ公開用のディレクトリに 配置したい。 そこで、sphinxの Makefileを見てみると、以下のようにとてみシンプルな構成になっている

html:
        $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
        @echo
        @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

この後半の $(BUILDDIR)/html がhtmlファイルの出力先なので、以下のようなオプションをつくって追記してみる

webUp:
        $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) /path/to/SphinxWeb
        @echo
        @echo "Build finished. The HTML pages are in /path/to/SphinxWeb."

これで make webUp とすることで、指定のディレクトリにHTMLファイルを生成してくれる。 たとえば、gitレポジトリとweb公開環境が共存するサーバ上で、最新のレポジトリにマージ後に、公開ディレクトリにhtmlを生成する場合は

$ git pull ../path/to/Sphinx.git
remote: Counting objects: 9, done.
remote: Compressing objects: 100% (5/5), done.
remote: Total 5 (delta 4), reused 0 (delta 0)
Unpacking objects: 100% (5/5), done.
From ../sphinx_memo
 * branch            HEAD       -> FETCH_HEAD
Updating 913e180..0da9fdf
Fast-forward
 index.rst                  |   16 +++++++++++-----
 installAndFirstProject.rst |   40 ++++++++++++++++++++++++++++++----------
 reSTandGit.rst             |    5 +++--
 3 files changed, 44 insertions(+), 17 deletions(-)

$ make webUp
sphinx-build -b html -d _build/doctrees   . /path/to/SphinxWeb
Running Sphinx v1.0.7
loading pickled environment... done
building [html]: targets for 3 source files that are out of date
updating environment: 0 added, 3 changed, 0 removed
reading sources... [100%] reSTandGit
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] reSTandGit
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in /path/to/SphinxWeb

というふうに、cloneしたgitのカレントディレクトリで git pull と make webUp を実行すれば、最新版への同期とhtml生成が行える。

脚注

[1]sphinx-quickstart時に Name prefix for templates and static dir [_]: がデフォルトのまま( _ )の場合の書き方です
[2]gitについては、別途検索するなり、オフィシャルサイトを参照ください。