vimのplugin Syntasticは結構気に入ってます.

Syntasticはファイル保存時に
そのファイルを文法チェックしてくれます.

さらに文法チェックの表示は
vim内に反映されるのでで簡単に取り扱えるので
非常に直感的です.

今回はこのpluginとSphinxを連携させてみます.
また、単なるReSTだと拡張部分のチェックに問題があるので調整してみます。

mazu,Syntasticはファイル保存時に
そのファイルを文法チェックしてくれます.

コンパイルや実行などする前にチェックが入るので,
エディタから別作業に移る前にある程度のチェックができます.

このため, 作業を移る回数が減って作業効率があがるわけです.

そのSyntasticではReSTチェックもできます.

現状の不満点

ただしSphinxのReSTには独自の拡張directiveがいろいろ入っているので

普通にReSTのチェックをすると「そのdirectiveはないですよー」っていう

エラーが数多く出てチェックになりません.

理由

これはSyntasticが文法のチェックに rst2xmlを使っているのが理由です.

rst2xmlはReSTのコアであるdocutilsに付属のコマンドで
sphinxの拡張directiveは認識しません.

Syntasticはrst2xmlの出力を解析して
vimに渡しているのでsphinx固有のdirectiveは理解できず,
エラーとなります.

対策 その1

rst2xmlの代わりにsphinx-buildを使います.

これでsphinxのdirectiveもチェックすることができます :D

次の不満点

sphinx-buildは重いです.

対策 その2

このことをSphinx MLで相談したところ

• Sphinxのディレクティブを反映したrst2null.pyを作るのは面倒
• 出力処理を省けば早くなるかも

ということで出力処理を省けるようなコードを教えてもらうことができました.

ありがとうございます > sphinx-ML

shpinxの出力処理を省略する

まず以下のコードをconf.pyに追加します:

from sphinx.builders import Builder

class NullBuilder(Builder):
    name = 'null'

def get_target_uri(self, docname, typ=None):
    return ''

def get_outdated_docs(self):
    """毎回全てのrstを処理対象にしたい場合は、以下を参考にこのメソッドを実装。
        https://bitbucket.org/birkenfeld/sphinx/src/b799dcd0bb9f/sphinx/builders/text.py#cl-30
    """
    return []

def write(self, build_docnames, updated_docnames, method='update'):
    pass

def prepare_writing(self, docnames):
    pass

def write_doc(self, docname, doctree):
    pass


def setup(app):
    app.add_builder(NullBuilder)

確認します.:

$ sphinx-build -t null

さて, この状態で時間比較してみます.:

$ time rst2xml
$ time sphinx-build -t xml
$ time sphinx-build -t null

数字はCore i3 2120Tのマシンのものです

rst2xml

2.005s

null

2.797s

xml

7.799s

おぉすごい改善効果...

後でTegra 1GHzのマシンでもやってみようか...

Syntasticの修正

Syntasticからsphinx-buildを使います.

ファイルを修正します:

$ mkdir ~/.bundle/syntastic/syntax_checkers/rst
$ cp ~/.bundle/syntastic/syntax_checkers/rst{.vim,}
$ vi ~/.bundle/syntastic/syntax_checkers/rst.vim

この作業で従来のrst2xml.pyにsphinx-buildを追加しています.

sphinx-buildのオプションは

-t null

上で示した出力なしを指定します

./doc

document source

./build

出力先, 出力しないけど必要です

次にrst.vimを調整します:

$ vi ~/.bundle/syntastic/syntax_checkers/rst.vim

次にsphinx用のvimスクリプトを調整します:

$ cp ~/.bundle/syntastic/syntax_checkers/rst/{rst,sphinx-build}.vim
$ vi ~/.bundle/syntastic/syntax_checkers/rst/sphinx-build.vim

ここでのポイントはError, Warningなどを
抽出する正規表現をsphinx-build用に修正することです.

残った問題点

2つあります

• 処理速度がまだ遅い, 私は我慢できる...かなぁ...
• sourceとdestのdirectoryが決め打ちになっている
• 普通のReSTを編集するにもsphinx-buildが立ち上がる

どちらもいまのところどうしようもないと思っています.

ReSTとsphinx用ReSTは別にするというのも考えていますが,
そこまで環境は作り込めていません

今回はとりあえずの方法を提示しました. 試していただけると幸いです. :D