remarkdown を巡る冒険 (原題: remarkdown versus Sphinx)
docutils はある形式の文書を別の形式に変換するフレームワークです。
このフレームワークを利用して rst2html や rst2latex などが提供されています。
しかし、docutils が標準で対応している入力形式は reST 形式に限られているので、
実際には reST 変換用のライブラリとして捉えられていました。
markdown 黄金時代
docutils や Sphinx の周囲では reST を中心としてドキュメントが記述されていますが、
2014年現在、軽量マークアップ言語の主流の座は markdown であると言っても過言ではないでしょう。
flavor が乱立していたり、拡張性に乏しかったり、困ったら HTML で書き下してあったりと、
記述能力が十分とはいえない markdown ですが、github を初めてとして様々な場所で用いられています。
4月1日はすでに過ぎたというのに Internet Draft になっているほどの人気ぶりです。
Sphinx に興味を持った人も、Sphinx と markdown の組み合わせを実現するために様々な試行錯誤を繰り返しています。
remarkdown の到来
そんな流れの中、remarkdown という docutils 拡張が発見されます。
remarkdown は docutils の拡張として動作し、reST のかわりに markdown を docutils の入力に使うことができます。
docutils は html や latex, Open Document (.odt) などの出力に対応しているので、
組み合わせることで markdown から様々なフォーマットへ出力することができるようになります。
remarkdown のインストール
remarkdown は PyPI にパッケージがアップロードされていないため、簡単にインストールする方法がありません。
そのため、次の方法でインストールを行います。
まず、pip を用いて github のアーカイブ経由でパッケージをインストールします。
$ pip install https://github.com/sgenoud/remarkdown/archive/master.zip
なお、setup.py に不備があるので*1、ファイルをひとつ手動でダウンロードする必要があります(パスは各自適当な場所に読み替えてください)。
$ curl -LO https://raw.githubusercontent.com/sgenoud/remarkdown/master/remarkdown/markdown.parsley $ mv markdown.parslay lib/python2.7/site-packages/remarkdown
remarkdown を使ってみる
remarkdown をインストールすると、一緒に md2html, md2latex, md2xml などのコマンドも一緒にインストールされます。
これらのスクリプトは markdown を入力として docutils を呼び出しています。
$ md2html test.md > test.html
Sphinx meets remarkdown
さて、ここからが本題です。
docutils と remarkdown の組み合わせができることを確認したところで、
今度は Sphinx と remarkdown を組み合わせてみることにします。
Sphinx を書き換える
Sphinx は docutils を利用して文書の変換を行っているのですが、
内部では reST 以外を想定していない作りになっています。
具体的には sphinx/environment.py の BuildEnvironment#read_doc() の中にこんな記述があります。
pub = Publisher(reader=SphinxStandaloneReader(),
writer=SphinxDummyWriter(),
source_class=SphinxSourceClass,
destination_class=NullOutput)
pub.set_components(None, 'restructuredtext', None)
Publisher のコンポーネントとして 'restructuredtext' を固定値で指定していますね。
入力フォーマット(パーサ)もここで決定しているので、markdown を入力として利用するには Sphinx を書き換える必要があります。
また、remarkdown は section ノードに必要な属性(ids, names)を正しくセットしていないので、
Sphinx を書き換える際についでに補正します。
Sphinx を書き換える、と言っても本体のソースコードを書き換えてしまうと、他の環境で使えなくなってしまうので、
conf.py の中から次のように書き換えを行います。
from docutils.core import Publisher class MarkdownPublisher(Publisher): def __init__(self, *args, **kwargs): Publisher.__init__(self, *args, **kwargs) # replace parser FORCELY from remarkdown.parser import MarkdownParser self.reader.parser = MarkdownParser() def publish(self): Publisher.publish(self) # set names and ids attribute to section node from docutils import nodes for section in self.document.traverse(nodes.section): titlenode = section[0] name = nodes.fully_normalize_name(titlenode.astext()) section['names'].append(name) self.document.note_implicit_target(section, section) # replace Publisher import sphinx.environment sphinx.environment.Publisher = MarkdownPublisher
また、conf.py を編集する際、ソースの拡張子の設定もついでに書き換えておくとよいでしょう。
source_suffix = '.md'
まとめ
remarkdown を使って docutils を拡張したり、Sphinx を拡張したりしてみました。
実験する範囲ではそれっぽく動くものの、ちゃんとドキュメントをつくり上げることを考えると
乗り越え無くてはならない課題はまだいくつか残っているようです。
僕は markdown があまり好きではないのでここで筆を置きますが、
興味がある人は続きにトライしてみてはいかがでしょうか。
*1:記事で紹介している markdown.parsley が入らない問題の他、entry_points がうまく定義出来ていないおかげで setup.py install を実行しても md2* コマンド群がインストールされない問題などがあります。
