昨日からFlask入門のやつをSphinxに移植していた。

• Flask 入門
• (epub版)
• (mobi版)

epubはさくっとmakeできたのだけど、Sphinx mobi builderにならってビルドしてみたけどNotImplementedErrorがでたので、Sphinxでmobiにするのは諦めてcalibreを使った。

Exception occurred:
  File "/Users/kzfm/Sphinx_projects/kindlebuilder/kindlebuilder/kindlewriter.py", line 295, in visit_image
    raise NotImplementedError("should implement this feature")
NotImplementedError: should implement this feature

ちょっと負けた感があるので、Shizuoka.pyまでにはいい感じのmobi変換のやり方を見つけておきたい。あとSend to Kindle Buttonでmobiをkindleに送れるように設定できるのだろうか？できるのであればSphinxでつくったGitHub Pagesにmobi用のボタンつけることができてかなり快適になると思うんだけどなぁ。

というような内容のLTをやれればと思っているので、興味があればShizuoka.pyに参加よろしくお願いします。

pipできるようになってた。

sudo pip install sphinx_bootstrap_theme

で使えるようになる。

あまりCSSをいじる気がなければこれでいいかなと思うが、弄りたい場合にはこっちのやり方のほうがいいかな。

あとで何かで使ってみようっと。

sphinx-quickstart でスキャフォールドを作成したら、sphinx-docxbuilderエクステンションを使えるようにするためクローンする

mkdir exts
cd exts/
hg clone https://bitbucket.org/haraisao/sphinx-docxbuilder

conf.pyの15-30行目あたりを編集

sys.path.insert(0, os.path.abspath('exts'))

# -- General configuration -----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 
extensions = ['sphinx-docxbuilder']

Makefileにdocx用の設定を追加

docx:
    $(SPHINXBUILD) -b docx $(ALLSPHINXOPTS) $(BUILDDIR)/docx
    @echo
    @echo"Build finished. now you can process the docx file. $(BUILDDIR)/docx."

文書を作成してみる

make docx

おお！

業務の文書をMSWordで提出しないとだめいうカルチャーの会社は多いと思うが、文書がフォルダに収められた後に、実際に再利用されるのを見たことがある人は少ないはず(探すの面倒だし)。

そういう場合にはReSTで書けるWIKIなんかを使うと常に参照できるうえに必要に応じてレポーティング出来ていいよねと思うのだが。僕はそういうスタイルでやっていたが超快適だった。

この快適さをmoin2+Sphinxで再現したい。

@ando_ando_andoに呼ばれてコミュニティfでSphinxサイト構築の手伝いをしてきた。彼のためのGit入門サイトが出来てたのを本人に教えてもらったのだけど、alias切ってなくてstatusとかcommitとかフルで手打ちしてたので、上の4つくらいはやっておいたほうがいいんじゃないかなぁ(と今思った)。

ついでに、@ando_ando_andoの「静岡の東部にはHaskellerが多い」という主張を検証するために、今週末に香香飯店あたりで集まって飲むことになったので、参加される方がいれば連絡してください。

Git+Sphinxでサイト管理

さて、彼はインフラエンジニアなので、作業メモとかblockdiagで描いた図なんかを手元で編集して、さくらのVPSで管理したいそうだ(GithubPagesでいいじゃんって言ったら、認証かけたいからそれはダメらしい)。

• _build/html/*もGit管理
• 共有リポジトリはベア(git init --bare)

という状態にして、サーバー側にGitの共有リポジトリ置いて、プッシュしたタイミングで公開サイトのほうも更新するようにフックを設定しておけばいいよねーという僕の提案に対し

pushしたらpullするようにフックを設定すると、もとのrstとかMakefileがサイトのディレクトリに含まれてしまい美しくない。_build/html以下のファイルだけを公開サイトに置きたいと言い出した

ここから、ちょっとハマった。

bareをやめる(失敗)

_build/html以下のみを公開するんだったら、サーバー側にpushした後に、一回cloneとかpushして作業ディレクトリを作ってからcpするなりしないといけないということなので、最初からbareオプション付けないで共有リポジトリ設定すればいいんじゃないと。

これは見事に失敗する

remote: error: refusing to update checked out branch: refs/heads/master
remote: error: By default, updating the current branch in a non-bare repository
remote: error: is denied, because it will make the index and work tree inconsistent
remote: error: with what you pushed, and will require 'git reset --hard' to match
remote: error: the work tree to HEAD.

メッセージ見たら、まぁそうだよなと思った。なので、これは却下した。

一回別の場所にclone(pull)してその後必要な物だけcp

結局サーバーにもクローンを作って_build/html/*を/var/www/html以下の適当なディレクトリにコピーするようにした（今ココ）。

手でコマンド叩いたけど、フックに書いておけばいいかな。

scpする(番外)

単にbuildしたやつをscpすればいいんじゃない？ってことで

を提案してみたが、彼の美意識にそぐわなかったのかボツった。

まとめ

cpするためだけにサーバー側に作業リポジトリを作っておくというのはなんとなく気持ち悪いんだけど、他にいい方法ないのかな？

Makefile書き換えて/var/www/htmlにbuildするようなオプション付けておけば、そもそも_buildをGitで管理しなくていいだろうとも思うんだけど、そこらへんの管理のさじ加減みたいなのもちょっと自信がない。

ToDo

Pythonプロフェッショナルプログラミングになんかヒントっぽいもの書いてないかなぁと読みなおす。

Pythonプロフェッショナルプログラミング
ビープラウド
秀和システム / 2940円 ( 2012-03-26 )

参考

Gitポケットリファレンス
岡本 隆史
技術評論社 / 2604円 ( 2012-07-10 )

エキスパートPythonプログラミング
Tarek Ziade
アスキー・メディアワークス / 3780円 ( 2010-05-28 )

2日目の途中で帰ってしまったので、朝コーヒーを飲みながら、残りのスライドを眺めてた。

• PyConJP2012 スライド・資料まとめ

HTMLテーマの拡張の話とDocutilsが参考になった。

そういえば二年くらい前に原稿書くときに使ったときはwordに出力するのに難儀したけど、今はdocxに出力できるらしいので、MSWORDな会社でも安心して使えますね。さらにmoin2を組み合わせれば、普段はWikiで使いつつ、必要に応じてSphinx経由で好きな書式で文書出力ってのもやりやすくなるだろうし。

GitHub Pagesを使って文書を管理したら快適そうだったので試してみた。

ゆるふわHaskellというものを書いてます。

Haskellで人工無脳をつくってみたいとか、PLEAC埋めたいとか、Invent with Pythonを書きなおしてみたいとか色々あったのでGitHub+Sphinxでやりたくなったというのがモチベーション。

基本的な流れとしては

1. gh-pagesというブランチを作る
2. sphinxtogithubというエクステンションを入れる
3. Sphinxで文章を書く
4. make htmlする
5. cp -pr _build/html/* ./でビルドされたhtmlをカレントディレクトリに移動する
6. commitしてpushすると公開できるようになる

となるが、4-5のステップはもうちょっとスマートにできると思う。ちなみに参考にしたのが以下のサイトだけど、オフィシャルのヘルプには一通り目を通しておくといいと思う。

• Creating Project Pages manually
• github pages に Sphinx で生成したドキュメントを公開する
• github のプロジェクトにSphinxドキュメントを良さげな感じにおきたい 其の一

GitHub+Sphinxのよさそうなところ(要検証)

• Issueの管理が楽
• pull requestで変更を取り込める
• コードの管理するよりソーシャルなやり取りの敷居が低そう

うちのサーバー(これとかこれ)も同じような構成でGit管理しているので、@ Git で集中リポジトリーに push したら、自動でワーク・ディレクトリーにも反映させるを見ながら、git pushしたらそのまま公開できるようにしたら快適。

ついでに、Sphinxで管理している文書もcommitしたらmake htmlするようにしてみた。

cd .git/
cd hooks/
cp post-commit.sample post-commit
vim post-commit

post-commitにはmake htmlって書いておくだけ

1
2
3

#!/bin/sh

make html

これでOK

余談だが、本読んだけどpost-update post-receiveの違いが分からなかったので後で調べる。

入門Git
濱野 純(Junio C Hamano)
秀和システム / 2310円 ( 2009-09-19 )

Sphinx 逆引き辞典を見ながら。

Jinja2のextendsを使えば簡単に挿入できるのね。

• ふじにずむ

今、欲しい物はこういうモノです。

Real World Haskellのように、文書のパラグラフ毎にコメントが入れられるようなシステム。それをSphinxでやりたい。つまりSphinxで文書を書いてmake htmlをするとパラグラフ毎にtwitterのOAuthかGoogleの認証使ってコメントが入れられるようなHTMLが出力されるナイスなドキュメント

実際にReal World Haskellのソースを追いかけてみると、jQuery Form Pluginを使っていてAjax化が簡単にできそうなので、別の題材で試してみる。もちろんflaskr

• statisticsにjqueryとjquery.form.jsを配置
• show_entries.htmlのformにid属性をつける(id='flaskr_form'っていう属性をつけた)
• layout.htmlにjsの設定を追加

layout.html

<script type="text/javascript" src="{{ url_for('static', filename='jquery-1.6.min.js') }}"></script> 
<script type="text/javascript" src="{{ url_for('static', filename='jquery.form.js') }}"></script> 
<script type="text/javascript"> 
        // wait for the DOM to be loaded 
        $(document).ready(function() { 
            // bind 'myForm' and provide a simple callback function 
            $('#flaskr_form').ajaxForm(function() { 
            $(document.body).load("/");
                alert("Thank you for your comment!"); 
            }); 
        }); 
    </script>

これでsubmitしたときにアラート画面が出るようになります。今回書いたコードはここからダウンロードできます。

というわけで、flaskかGAEでパラグラフのidをクエリとしてコメントをjsonで返すサービスを用意しておいて、SphinxにjQuery埋め込んでコメントサービスと連携させれば望みのものはできそうな気がするんだけど、Sphinxのパラグラフに固有のIDを付加する方法がわからない。

どうやるのがいいのかなぁ

エキスパートPythonプログラミング
Tarek Ziade
アスキー・メディアワークス / 3780円 ( 2010-05-28 )

wikiやめたのでSphinxにメモるようにしてます。

• さくらのVPS設定メモ

で、ちょっと悩んでいるのがmake html後の手順だ。

現在/var/www/html以下はgitで管理していて、/var/www/html/[sphinx_html]みたいにドキュメントを置こうかなと考えているんだが、それってクライアント側でmake htmlして_build/htmlをcp -Rして/var/www/htmlを管理している方のGitに管理させるのがいいのかそれとも分けて管理してサーバー側で改めてmake htmlするようにしたほうがいいのかと。

あとはmake htmlしたあとの_buildディレクトリってもうちょっと自動的に公開されるようにできんかなと。

自動化といえば作業しているrstを監視しといてrstが更新されたら裏で自動的にmake htmlかかるようにできんかなとかも思った。

追記　11.04.02

Makefile読んだらmake htmlは

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

ということなのでSPHINXBUILDつまりsphinx-buildコマンドを直接呼び出して明示的にBUILDDIRを指定してやればいいってことだった。