rstblog で新規にロールを作成してみる
written on Thursday, February 2, 2012
rstblog を拡張するには modules 以下に自分のモジュールを設置し、config.yml で使用するモジュールを設定する。
拡張方法には主に reStructuredText のマークアップの種類を増やす方法と Jinja2 のテンプレートを拡張する方法がある。
デフォルトの modules ディレクトリにある latex.py は reStructuredText を拡張するもので、tags.py は Jinja2 を拡張する。
reStructuredText を拡張していくには`ロール`と`ディレクティブ`という概念がある。
ロールやディレクティブはみんな大好き Sphinx でも同じなので Sphinx も参考になる。
例
ここでは reStructuredText で文字を太字にするだけの bold.py を作ってみる。
文書中の文字を :bold:`太字にする` のがロール
この場合`太字にする`の部分を <b> タグで括り太字にする。
---
active_modules: [pygments, tags, blog, latex, bold]
まず config.yml で active_modules で使用するモジュール名を設定し、modules に設置する。
拡張方法は docutils のメソッドを使って拡張していく。
モジュールは HTML 生成時に必ず setup という関数が呼ばれる。なのでまずこの関数を定義する。
# -*- coding: utf-8 -*-
from docutils import nodes
from docutils.parsers.rst import roles
def bold_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
text = u'<b>%s</b>' % text
nodes.raw('', text, format='html')
return [nodes.raw('', text, format='html')], []
def setup(builder):
roles.register_local_role('bold', bold_role)
setup() 内で roles.register_local_role() の第一引数に reStructuredText で記述するロール名、第二引数で実行するオブジェクトを設定する。
def bold_role() で rawtext では:bold:太字にする が設定される。
また text には`太字にする`という文字が来る。
戻り値として [], [] というリストを戻す。
最初のリストには装飾したテキストの内容を返せば良い。
二つ目のリストはエラーメッセージなどを返すようなので、空のリストを返す。
というわけでロールは割と簡単に実装できた。